[Spring Boot Tutorial] 13. OpenAPI 3.0를 이용한 REST API 문서 만들기 (Swagger v3)

1. OpenAPI 3.0
   1. OAS 란?
   2. Swagger 란?
   3. springdoc-openapi
2. 설정
   1. 의존성 라이브러리 추가
   2. 프로퍼티 설정 (operations-sorter, display-query-params-without-oauth2)
   3. Swagger Info 설정
3. Swagger-ui 실행
   1. /swagger-ui/index.html
   2. Swagger-ui 실행 및 csrf token 문제점

---

2. 설정

2.1. 의존성 라이브러리 추가

pom.xml에 springdoc-openapi 을 추가합니다.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.6</version>
</dependency>

2.2. 프로퍼티 설정

springdoc:
  version: '@project.version@'
  api-docs:
    path: /api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    operations-sorter: alpha
    tags-sorter: alpha
    path: /swagger-ui.html
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true
    doc-expansion: none
  paths-to-match:
    - /api/**

• springdoc
  • api-docs.path
    • 기본값 : /v3/api-docs
    • spring boot 웹 애플리케이션의 api를 OpenAPI 3을 이용하여 json 형식화 한것의 경로
  • default-consumes-media-type
    • 기본값 : application/json
    • request media type 의 기본 값
  • default-produces-media-type
    • 기본값 : */*
    • response media type 의 기본 값
  • swagger-ui.operations-sorter
    • 기본값 : 컨트롤러 내에서 정의한 api 메서드 순
    • 태그 내 각 api의 정렬 기준
    • alpha(알파벳 오름차순), method(http method 순)
  • swagger-ui.tags-sorter
    • 태그 정렬 기준
  • swagger-ui.path
    • 기본 값 : /swagger-ui.html
    • Swagger HTML 문서 경로
  • swagger-ui.disable-swagger-default-url
    • swagger-ui default url인 petstore html 문서 비활성화 여부
    • ※ v1.4.1 이상 버전부터 지원합니다.
  • swagger-ui.display-query-params-without-oauth2
    • 기본 값 : false
    • json화 된 config파일 대신 파라미터를 이용하여 swagger-ui에 접근하도록 합니다.
    • api-docs(/api-docs) 및 swagger-ui.configUrl(/api-docs/swagger-config)를 두번씩 호출하는 것을 방지합니다.
    • ※ v1.4.1 이상 버전부터 지원합니다.
  • swaggerui.doc-expansion
    • 기본 값: list
    • tag와 operation을 펼치는 방식에 대한 설정
    • String=["list", "full", "none"]
    • none으로 설정할 경우, tag 및 operation이 모두 닫힌채로 문서가 열립니다.
  • paths-to-match
    • OpenAPI 3 로 문서화할 api path 리스트

※ 더 자세한 설정정보를 알고 싶다면 springdoc-openapi를 참고해주세요.

2.2.1. operations-sorter 설정에 따른 api 출력화면

springdoc.swagger-ui.operations-sorter : alpha

springdoc.swagger-ui.operations-sorter : method
DELETE → GET → PATCH → POST → PUT 순서

2.2.2. display-query-params-without-oauth2 설정에 따른 리소스 호출 횟수

swagger-ui.display-query-params-without-oauth2 : false
/api-docs와 /api-docs/swagger-config를 2번씩 호출합니다.

swagger-ui.display-query-params-without-oauth2 : true
/api-docs/swagger-config 를 호출하지 않으며, 파라미터를 이용하여 swagger-ui html문서를 호출합니다.

2.3. Swagger Info 설정

OpenAPI 의 Info 설정을 별도하지 않을 경우 위와 같은 모양으로 Swagger-ui 페이지가 아래와 같이 자동 설정됩니다.

Swagger-ui 기본 화면

OpenAPI bean 을 이용하여 Swagger-ui를 구성하는 메시지를 수정해봅시다.

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;

@Component
public class OpenApiConfig {

  @Bean
  public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
    Info info = new Info().title("Demo API").version(appVersion)
            .description("Spring Boot를 이용한 Demo 웹 애플리케이션 API입니다.")
            .termsOfService("http://swagger.io/terms/")
            .contact(new Contact().name("jini").url("https://blog.jiniworld.me/").email("jini@jiniworld.me"))
            .license(new License().name("Apache License Version 2.0").url("http://www.apache.org/licenses/LICENSE-2.0"));

    return new OpenAPI()
            .components(new Components())
            .info(info);
  }

}

OpenAPI 빈을 설정한 후의 Swagger-ui 화면입니다.

---

3. Swagger-ui 실행

3.1. /swagger-ui/index.html

springdoc.swagger-ui.path에 정의한 경로(default: swagger-ui.html)로 접속할 Swagger 관련 설정값을 이용하여 Swagger-ui HTML 페이지로 Redirect 됩니다.

궁극적인 Swagger-ui 도착지 주소는 /swagger-ui/index.html 이지만, 이 페이지는 API 명세를 만들기 위해 api-docs에 대한 파라미터를 필수적으로 입력받아야 생성됩니다.

만일, 파라미터를 설정하지 않을 경우에는 아래와 같은 petstore 페이지가 출력됩니다. 파라미터 미설정시 표현할 defaultUrl 설정을 끄고 싶다면 springdoc.swagger-ui.disable-swagger-default-url 속성을 true로 설정하면 됩니다.

query-param 을 url로 표출할 것인지에 대한 설정에 따라 url에서 이용되는 필수 파라미터가 달라집니다.
이에 대한 설정은 springdoc.swagger-ui.display-query-params-without-oauth2 에서 행해집니다.
이 값이 true 일 경우에는 Swagger-ui 를 구성하는데 필요한 설정값들을 파라미터로 표출하고,
false 일 경우에는 configUrl만 받습니다.

• false
  • /swagger-ui/index.html?configUrl=/api-docs/swagger-config
• true
  • /swagger-ui/index.html?operationsSorter=method&tagsSorter=alpha&url=/api-docs

※ 프로퍼티 설정 참고

3.2. 실행

GET api를 실행한 결과 화면입니다.
200 status와 ResponseBody가 정상적으로 출력됨을 확인할 수 있네요!