[SpringDoc] Spring에서 Swagger 문서 작성 (with springdoc-openapi)

SpringDoc

springdoc-openapi 라이브러리는 스프링 부트 프로젝트의 API 문서 생성 자동화를 해준다. 지원하는 주석을 기반으로 작성된 API의 기본적인 정보 및 추가로 입력된 정보를 추론하여 작성된다.

 

최신버전 확인 및 공식 문서

OpenAPI 3 Library for spring-boot

 

---

 

 

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 이 추가되어 요청된다.