Swagger UI 설정하기

의존성 라이브러리 추가

dependencies {
    // ......
    // swagger 2
    // compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
    compile("io.springfox:springfox-swagger2:2.9.2") {
        exclude module: 'swagger-annotations'
        exclude module: 'swagger-models'
    }
    compile("io.swagger:swagger-annotations:1.5.21")
    compile("io.swagger:swagger-models:1.5.21")
    // ......
}

Swagger 활성화

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }
}

브라우저에서 http://localhost:8080/swagger-ui.html 를 접속하면 Swagger UI 가 실행된 것을 확인할 수 있습니다.

컨트롤러에 annotation 추가

Api annotation 을 추가하면 Swagger UI 에 컨트롤러의 메소드가 자동으로 등록됩니다.

ApiOperation annotation 을 추가하면 한글 설명을 메소드에 추가할 수 있습니다.

ApiImplicitParams 을 이용해 파라미터에 대한 한글 설명을 추가할 수 있습니다.

@Api(value = "Menu")
@RequiredArgsConstructor
@RestController
public class MenusApiController {

    private final MenusService menusService;

    @ApiOperation(value = "메뉴 저장", notes = "메뉴 아이템을 신규등록합니다.")
    @PostMapping("/v1/settings/menu")
    public ResponseWithDataDto save(@RequestBody MenusSaveRequestDto menusSaveRequestDto) {
        return menusService.save(menusSaveRequestDto);
    }

    @ApiOperation(value = "메뉴 조회", notes = "메뉴 아이템을 조회합니다.")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "메뉴 ID", required = true, dataType = "int", paramType = "path", defaultValue = ""),
    })
    @GetMapping("/v1/settings/menu/{id}")
    public ResponseDto findById(@PathVariable Integer id) {
        return menusService.findById(id);
    }
}

헤더 인증정보 추가

List<Parameter> 를 이용해 헤더에 인증정보를 추가할 수 있습니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {

        ParameterBuilder aParameterBuilder = new ParameterBuilder();
        List<Parameter> aParameters = new ArrayList<Parameter>();

        aParameters.clear();

        aParameterBuilder.name("HTTP_AUTH_ACCESS_ID").
                modelRef(new ModelRef("string")).
                parameterType("header").
                required(true).
                build();
        aParameters.add(aParameterBuilder.build());
        aParameterBuilder.name("HTTP_AUTH_ACCESS_KEY").
                modelRef(new ModelRef("string")).
                parameterType("header").
                required(true).
                build();
        aParameters.add(aParameterBuilder.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(aParameters)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/v1/**"))
                .build();
    }
}

DTO 에 예제값 표시

@Getter
@NoArgsConstructor
public class MenusSaveRequestDto implements Serializable {

    @ApiModelProperty(example = "0")
    private Integer pidx;
    @ApiModelProperty(example = "테스트 메뉴")
    private String menuName;
    @ApiModelProperty(example = "Y")
    private String useyn;
}