[SpringDoc] Spring에서 Swagger 문서 작성 (with springdoc-openapi)
SpringDoc
springdoc-openapi 라이브러리는 스프링 부트 프로젝트의 API 문서 생성 자동화를 해준다. 지원하는 주석을 기반으로 작성된 API의 기본적인 정보 및 추가로 입력된 정보를 추론하여 작성된다.
SpringDoc 종속성 추가 및 설정
// maven
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>latest-version</version>
</dependency>
// gradle
implementation("org.springdoc:springdoc-openapi-ui:latest-version") // spring doc
종속성 추가 후 http://localhost:8080/v3/api-docs/ 에 접속했을 때 OpenAPI 설명 json 화면이 출력된다.
사용자 지정 경로를 사용하려면 application.yml 파일에 다음과 같이 작성한다.
springdoc:
api-docs:
path: /api-docs
http://localhost:8080/api-docs/ 경로로 접근이 가능해진다.
Swagger UI 설정
위의 종속성을 추가했다면 http://localhost:8080/swagger-ui.html 를 통해 기본적으로 등록된 api를 swagger ui로 확인할 수 있다.
마찬가지로 사용자 지정 경로를 사용하려면 application.yml 파일에 다음과 같이 내용을 추가하면 된다.
springdoc:
swagger-ui:
path: swagger-ui-custom.html
http://localhost:8080/swagger-ui-custom.html 경로로 접근이 가능해진다.
swagger ui 에 표시되는 HTTP 메서드들의 정렬 순서를 변경하려면 다음의 내용을 추가하면 된다.
springdoc:
swagger-ui:
operationsSorter: method #alpha or method
API에 설정을 하기 위해 다음과 같은 기능들을 사용할 수 있다.
@RestController
@RequestMapping
class BaseController {
@Operation(hidden = true)
@GetMapping("/health_check")
fun healthCheck() = "It's working in futureInvestServer"
@Operation(summary = "서버 현재 시간 조회", security = [SecurityRequirement(name = "bearer-key")])
@ApiResponses(
value = [
ApiResponse(
responseCode = "200",
content = [Content(
mediaType = "application/json",
schema = Schema(implementation = Long::class),
examples = [ExampleObject(name = "name", value = "1648787755769")]
)]
)
]
)
@GetMapping("/currentServerTime")
fun getCurrentServerTime(): Long = System.currentTimeMillis()
}
- Operation - Swagger UI에 표시할 데이터를 정의하거나 추가 속정을 정의하는데 사용한다.
- hidden - 해당 요청을 Swagger UI에서 숨김
- summary - 해당 요청의 간략한 설명을 추가, 120자 이내
- security - bearer auth , basic auth 등 요청의 보안 등록 정보를 추가
- ApiResponse - API 응답에 대한 정의를 추가하는데 사용
- responseCode - 응답 코드
- content - 응답 코드에 대한 내용
위의 설정이 된 Controller에 대한 Swagger UI에 표시된 정보이다.
Swagger UI 요청에 Authorization Header 추가하기
@Configuration
class OpenApi30Config {
@Bean
fun customOpenAPI(): OpenAPI? {
return OpenAPI().components(
Components().addSecuritySchemes(
"bearer-key",
SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
)
)
}
}
위 설정은 Swagger 요청에 대해 JWT 포맷의 bearerAuth 인증을 할 수 있게 해준다.
우측 상단의 Authorize 버튼이 활성화 되고 해당 버튼을 클릭하면 다음과 같은 인증 값을 입력하는 화면이 나온다.
키를 입력 후 Authorize 버튼을 클릭하면 Security 가 적용된 API 요청에 한해 요청 시 header에 Authorization 이 추가되어 요청된다.