[Spring] - Swagger 기본사용법 및 API 문서자동화

Spring으로 Rest API를 개발하고 그 API에 대한 문서를 정리하여 해당 API를 사용하는 클라이언트 및 서버 개발자들에게 문서를 정리해서 공유해야하는데 이때 Swagger를 이용하게되면 이런 작업을 보다 편리하게 할 수 있고 API 문서 자동화 뿐만 아니라 UI에서 직접 API 테스트로 할 수 있다. 예제코드와 함께 기본세팅법 부터 알아보자

개발환경

Spring Boot
Maven
Java 11

Swagger 의존성 추가

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version> 
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger를 사용하기위해 pom.xml에 해당 의존성을 추가하자

Swagger 설정 추가

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String API_NAME = "Study API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Study API 명세서";

    @Bean
    public Docket api() {
        Parameter parameterBuilder = new ParameterBuilder()
            .name(HttpHeaders.AUTHORIZATION)
            .description("Access Tocken")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(false)
            .build();

        List<Parameter> globalParamters = new ArrayList<>();
        globalParamters.add(parameterBuilder);

        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(globalParamters)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kjh.study.api"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
	return new ApiInfoBuilder()
		.title(API_NAME)
		.version(API_VERSION)
		.description(API_DESCRIPTION)
		.build();
    }
}

Swagger 설정 코드이다. 해당설정이 무엇을 의미하는지 한번 알아보자.

ApiInfo apiInfo()

API의 이름은 무엇이며 현재 버전은 어떻게 되는지 해당 API에 대한 정보를 적어주면된다.

 

ParameterBuilder

API를 테스트할때 모든 API에 전역 파라미터를 설정한다.
해당소스는 모든 API 테스트시 header에 'Autorization' 이라는 값을 추가하도록 했다.

 

RequestHandlerSelectors.basePackage(String packageName)

Swagger를 적용할 클래스의 package 명을 적어준다.

 

PathSelectors.any()

해당 package 하위에 있는 모든 url에 적용시킨다. /test/**로시작되는 부분만 적용해주고싶다면
PathSelectors.ant(String pattern) 메서드에 url parttern을 추가해주면된다.

샘플 API 작성

간단하게 유저정보를 조회, 등록, 수정, 삭제하는 API를 작성하였다.

이번장에서는 Rest API 설계에 대한 부분보다는 Swagger를 API에 적용시키는것에 대해서만 설명한다.

Swagger 화면

주소창에 호스트:포트/swagger-ui.html를 입력하게되면 다음과 같이 Swagger가 적용된 화면을 볼 수 있다.
이제 Swagger에서 제공해주는 기능들을 적용시켜보자

Swagger 기능

일단 해당API가 어떤API인지를 알아야 한다. @ApiOperation 어노테이션으로
해당 API에 대해 간단한 설명을 적을 수 있다.

API에서 중요한것중 하나가 응답이 어떤구조로 내려오며 각 응답되는 key가 어떤의미인지 알아야 한다.
그러기 위해선 응답되는 객체의 필드에 @ApiModelProperty 어노테이션으로 해당 필드가 어떤의미인지 적을수 있다.

@ApiModelProperty 어노테이션을 적용하게되면 다음처럼 확인할 수 있다.
테스트를 하려면 우측상단에 Try it out버튼을 클릭해보자.

테스트를 하고나면 해당 API를 호출했을때 응답데이터가 정상적으로 내려온걸 확인할 수 있고
json확장자의 파일로 API 결과를 다운로드 받을 수 있다.

API를 요청할때 파라미터를 필요로 하는 API가 있다. 이때 위 사진처럼 Description에 저렇게만 적어두면
저 값이 어떤의미인지 클라이언트 측은 알 수가 없다. 지금은 예제코드라 유저ID라는걸 짐작할 수 있지만
해당 파라미터가 어떤의미인지는 명시해줄 필요가 있다.

@ApiImplicitParam 어노테이션을 적어주면 해당 파라미터명은 무엇이고 파라미터값은 어떤의미인지 알 수 있다.

파라미터가 2개이상이고 필수여부도 지정해줄땐 위와같이 @ApiImplicitParams 어노테이션을 사용해주고
@ApiImplicitParam 어노테이션 속성에다 필수여부를 지정해주면된다.

주의할 점은 ApiImplicitParam 어노테이션으로 required = false를 지정했다고 해서 @PathVariable 어노테이션에도
적용되는건 아니니 이부분은 주의하자

하지만 요청 파라미터를 N개이상 받을땐 @PathVariable이나 @RequestParam을 N번만큼 적지않고
Java Bean 스펙을 구현한 DTO 클래스를 만들지만 매개변수에 DTO 클래스를 넣으면
아래처럼 요청 파라미터로 넘기지않은 불필요한 필드들도 나오게 된다.

이처럼 @ApiIgnore 어노테이션을 선언해주면 해당정보는 화면에 나오지 않게된다.
@ApiIgnore 어노테이션은 클래스, 메소드에도 올 수 있으며 Swagger에서 클라이언트로부터 공유하고 싶지않은
곳에다 해당 어노테이션을 선언해주면 보이지 않게된다.

@RequestBody 어노테이션이 선언된 API를 테스트 할때는 json 포맷으로 데이터를 입력할 수 있게끔 제공해주고
요청을 하게되면 content-type이 application/json로 바뀌고 request body에 데이터가 담겨 전송된다.

데이터를 등록하고 조회해보니 정상적으로 들어갔다.

Response를 보면 Swagger에서는 200, 401, 403, 404 같은 기본상태코드에 대한 디폴트메세지를 제공해준다.
이 기본상태코드들을 제거하려면 Swagger JAVA 설정코드쪽에
.securitySchemes(Collections.singletonList(apiKey())) 이부분을
.securitySchemes(Collections.singletonList(apiKey())).useDefaultResponseMessages(false) 이렇게 고쳐주자.

@ApiResponse 어노테이션을 선언해주면 API 상태코드값별로 메세지를 커스텀할 수 있다.

 

필자가 API를 개발하고나면 항상 문서작성을 해야하는 번거로움이 있었고 JAVA 코드에 어노테이션이 좀 많이 생기다보니 지저분 해보일 수 있지만 Swagger를 적용해보고 제공해주는 기능들을 보니 나쁘지않은것 같았다.