[Spring] Swagger 3.0 with Spring boot 2.X :: springfox

Swagger 세팅하기

0. Dependency 추가

Maven

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle

# https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

1. Yaml 설정

application.yml

swagger:
  project:
#    external-host: local.domain.com # 도메인 URL (localhost 사용시 명시 안해도 됨)
    base-package: com.java.test.domain # 베이스 패키지

2. 컨피그 파일 생성

SwaggerConfiguration.java

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Value("${swagger.project.base-package}")
    private String basePackage;

//    @Value("${swagger.project.external-host}")
//    private String externalHost;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage(this.basePackage))
                .paths(PathSelectors.ant("/**"))
                .build()
//                .host(this.externalHost)
                .apiInfo(this.apiInfo())
                .useDefaultResponseMessages(false);
    }

    /**
     * API Documents Information
     * @return
     */
    private ApiInfo apiInfo() {
        String title = "Swagger API Documents"; // 스웨거 UI 타이틀
        String version = "1.0.0";
        String license = "Dongmin All rights reserved";

        return new ApiInfoBuilder()
                .title(title)
                .version(version)
                .license(license)
                .build();
    }
}

3. 서버 스타트

4. 아래 URL 접속

localhost:8080/swagger-ui/

Swagger 문서 관리하기

Swagger DTO 필드 세팅

import io.swagger.annotations.ApiModelProperty;

public class Request {

	@ApiModelProperty(value = "이름", example = "KIM", required = true)
	private String name; // 필수값
    
    @ApiModelProperty(value = "나이", example = "5")
    private Integer age;
}

public class Response {

	@ApiModelProperty(value = "회사명", example = "CJ")
	private String company;
    
    @ApiModelProperty(value = "부서", example = "개발팀")
    private String department;
}

• required = true 로 설정한 필드는 필수 값이다. 디폴트: required = false

컨트롤러 설명 추가하기

@Api(tags = "나의 컨트롤러")
@RestController
@RequestMapping("/api")
public class MyController {
	...
}

컨트롤러 엔드포인트 API 설명 및 메소드 파라미터 설명 추가하기

@Api(tags = "나의 컨트롤러")
@RestController
@RequestMapping("/api")
public class MyController {

  @ApiOperation(value = "Swagger 예시 API")
  @ApiImplicitParams({
  		@ApiImplicitParam(name = "param1", value = "1번파라미터", required = true, dataType = "string", example = "12345"),
		@ApiImplicitParam(name = "param2", value = "2번파라미터", required = false, dataType = "int", example = "100"),
  })
  @GetMapping("/example")
  public ResponseEntity<String> example(@RequestParam String param1, @RequestParam String param2) {
    // code
  }
  
}

컨트롤러 메소드의 일부 파라미터 스웨거 문서에서 제외하기

해당 파라미터에 @ApiIgnore 추가

@RestController
@RequestMapping("/api")
public class MyController {

  @GetMapping("/example")
  public ResponseEntity<String> example(@RequestParam String param1, @ApiIgnore @RequestParam String param2) {
    // code
  }
  
}

스웨거 문서에서 엔드 포인트 제외하기

단일 메소드

@RestController
@RequestMapping("/api")
public class MyController {

  @ApiIgnore
  @GetMapping("/example")
  public ResponseEntity<String> example(@RequestParam String param1, @RequestParam String param2) {
    // code
  }
  
}

클래스 단위

@ApiIgnore
@RestController
@RequestMapping("/api")
public class MyController {

  @GetMapping("/example")
  public ResponseEntity<String> example(@RequestParam String param1, @RequestParam String param2) {
    // code
  }
  
}