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

스프링 부트를 사용한 예제 애플리케이션을 AWS를 통해 모노리식에서 MSA로 MSA에서 다시 컨테이너 오케스트레이션으로 개선해나가는 과정을 모두 담은 강의를 출시하게 되었습니다.
강의 과정에서 15개 이상의 서비스를 사용하게 됩니다.
그래서 클라우드 개발자가 아닌 개발자, 학생 분들도 AWS의 폭넓은 지식을 쉽고 빠르게 습득할 수 있는 기회가 될 수 있다고 생각합니다!
배너를 누르면 강의로 이동됩니다.

블로그를 통해 구매하시는 분들에게만 10%할인 쿠폰을 증정중입니다.
꼭 아래 쿠폰번호를 입력해 주세요!

16861-259843d6c2d7

---

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