Swagger UI 꾸미기

Swagger UI 꾸미기

이 문서에서는 설정된 Swagger UI에 정보를 추가하는 방법에 대해서 알아본다.

문서 정보

문서에 대한 기본 정보는 Swagger Configuration 파일에서 설정할 수 있다. Docket bean을 생성하는 부분에 다음과 같이 추가로 설정한다.

.apiInfo(
	new ApiInfoBuilder()
		.title("문서의 제목")
		.description("문서의 설명")
		.version("문서의 버전")
		.license("라이선스 정보")
	.build()
)

컨트롤러 정보

컨트롤러 정보를 추가하고 싶을 경우 컨트롤러 위에 ApiAnnotation을 작성한다.

@RestController
@RequestMapping("/sample")
@Api(tags = "샘플 REST API")
public class SampleController {

}

매핑 작업 설명

매핑에서 수행하는 작업에 대한 설명을 설정하고 싶을 경우 다음과 같이 @ApiOperation 을 사용한다.

@ApiOperation(value = "샘플 매핑")
@GetMapping("/")
public String home(){
    return "home";
}

매핑 요청 파라미터 설명

매핑의 파라미터에 대해 설명을 설정하고 싶을 경우 다음과 같이 @ApiImplicitParams와 @ApiImplicitParam을 사용한다.

@ApiImplicitParams({
    @ApiImplicitParam(name = "id", dataType = "String", value = "회원아이디", required = true),
    @ApiImplicitParam(name = "pw", dataType = "String", value = "회원비밀번호", required = true),
})
@PostMapping("/login")
public boolean login(@RequestParam String id, @RequestParam String pw){

}

매핑 응답 설명

매핑에 대한 응답 정보를 추가하고 싶을 경우 다음과 같이 @ApiResponse , @ApiResponses Annotation을 Mapping 상단에 추가한다.

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "로그인 성공"),
    @ApiResponse(code = 404, message = "일치하는 로그인 정보 없음"),
    @ApiResponse(code = 500, message = "데이터베이스 연결 오류")
})
@PostMapping("/login")
public boolean login(@RequestParam String id, @RequestParam String pw){

}

Swagger에서 제공되는 기본 응답정보를 사용하고 싶지 않을 경우 Swagger Custom 설정파일의 Docket 생성 부분에 다음 작업을 추가해야한다.

.useDefaultResponseMessages(false)