Table of Content
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;
}