Swagger 적용 방법

의존성 추가

dependencies {
	...
	implementation 'io.springfox:springfox-swagger2:2.9.2'
	implementation 'io.springfox:springfox-swagger-ui:2.9.2'
	...
}

 

SwaggerConfig

의존성을 추가했다면 스웨거에 대한 설정을 할 수 있는 config파일을 만들어 스웨거 문서를 생성하는데 필요한 설정을 추가합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.project.example.controller"))
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("example project REST API")
                .description("Example project Java Backend REST API Guide Document")
                .contact(new Contact(
                        "example project",
                        "https://www.project.com/",
                        "example@project.com"))
                .version("1.0")
                .build();
    }
}

 

@EnableSwagger2

어노테이션을 통해 Swagger2 버전을 활성화 합니다.

 

Docket

Swagger 설정의 핵심이 되는 Bean입니다.

Docket의 설정 정보는 다음과 같습니다.

 

annotation	description
useDefaultResponseMessages()	false로 설정시, swagger에서 제공해주는 응답코드 ( 200,401,403,404 )에 대한 기본 메시지를 제거합니다.
groupName()	Docket Bean이 한 개일 경우 * 기본 값은 default이므로, 생략가능합니다. 여러 Docket Bean을 생성했을 경우 * groupName이 충돌하지 않아야 하므로, 각 Docket Bean의 name을 명시합니다.
select()	ApiSelectorBuilder를 생성합니다.
apis()	api 스펙이 작성되어 있는 패키지를 지정합니다.
paths()	apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화합니다.
apiInfo()	제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출합니다.
consumes()	HTTP 요청시 어떤 문서 타입을 지정할 수 있는지를 나타냅니다.
produces()	응답 객체 반환시 어떤 문서 타입으로 반환 하는지를 나타냅니다.

스웨거가 적용됬다면 {server-url}/swagger-ui.html 에서 만들어진 문서를 확인할 수 있습니다.

 

Controller

스웨거를 적용한 후, API에 대한 자체 스펙은 컨트롤러에서 작성하게 됩니다.

다음은 실제로 작성되어있는 코드의 예시를 보여줍니다.

@Api(tags = "ExampleController", description = "DATA API")
@RequiredArgsConstructor
@RestController
@RequestMapping("/api/datas")
public class exampleController {
    @ApiOperation(
            value = "데이터 호출",
            notes = "파라미터로 요청한 데이터를 호출 합니다.")
    @ApiImplicitParams({
            @ApiImplicitParam(name="param1", value = "param1 이름"),
            @ApiImplicitParam(name="param2", value = "param2 이름"),
            @ApiImplicitParam(name="param3", value = "param3 이름")})
    @GetMapping
    public ResponseEntity<?> getData(@RequestParam(value = "param1", defaultValue = "") String param1,
                                     @RequestParam(value = "param2", defaultValue = "") String param2,
                                     @RequestParam(value = "param3", defaultValue = "") String param3)
                                     {
                                     ...
                                       }

 

• 개발중인 프로젝트에 대해서는 각 Controller의 @requestMapping가 적용된 메서드마다 @ApiOperation, @ApiImplicitParams를 작성하도록 합니다.
• @ApiResponses와 example은 기본값을 사용하도록 합니다.

각 설정값에 대한 설명은 다음과 같습니다.

annotationdescription

@Api	해당 클래스가 Swagger 리소스라는 것을 명시합니다. value * 태그를 작성합니다. tags * 사용하여 여러 개의 태그를 정의할 수도 있습니다.
@ApiOperation	한 개의 operation(즉 API URL과 Method)을 선언합니다. value * API에 대한 간략한 설명(제목같은 느낌으로)을 작성합니다. notes * 더 자세한 설명을 작성해줍니다.
@ApiResponse	operation의 가능한 response를 명시합니다. code * 응답코드를 작성합니다. message * 응답에 대한 설명을 작성합니다. responseHeaders * 헤더를 추가할 수도 있습니다.
@ApiImplicitParam	파라미터에 대한 정보를 명시합니다. name * 파라미터를 지정 합니다. value * 파라미터 정보를 작성합니다. required * 필수 파라미터이면 true, 아니면 false를 작성합니다. dataTypeClass * 파라미터의 타입을 작성합니다. example * 테스트를 할 때 보여줄 예시를 작성합니다.

 

참고자료

---

• https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started
• https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X