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

2020. 6. 18. 11:28Spring/Spring Boot Tutorial

300x250
반응형
  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 출력화면

85

springdoc.swagger-ui.operations-sorter : alpha


86

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


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

87

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

88

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


2.3. Swagger Info 설정

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

89

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);
  }

}

90

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로 설정하면 됩니다.

96

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가 정상적으로 출력됨을 확인할 수 있네요!

93

300x250
반응형
  • 프로필사진
    traeper2021.01.26 14:37

    OpenAPI 관련 삽질중이었는데 도움이 많이 되었습니다.
    감사합니다. :)

  • 프로필사진
    빵더쿠2021.05.11 16:39

    지니얌

    "springfox 라이브러리는 OpenAPI 3.0을 지원하고 있지 않습니다."

    -> 이 코멘트 springfox-boot-starter 를 사용한 3.0.0 버전도 마찬가지로 해당하는 사항일까?

    [GitHub - springfox/springfox: README.md]
    https://github.com/springfox/springfox#springfox

    -> @EnableOpenApi 따위가 보임!

    [Made open api 3.0.0 the default · springfox/springfox-demos | Examples repository]
    https://github.com/springfox/springfox-demos/commit/ee64c326cb45f140ef17c3f0ad620b359a54c302

    -> 단순히 Docket 빈을 생성하지 않으므로 OAS_30 적용되는 예제 소스 커밋 인데,
    OpenAPI 3.0 스펙을 맞춘 api-docs 제작을 지원하고 있는 것 아닌가?


    [Maven Repository: io.springfox » springfox-boot-starter]
    https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter

    -> 이게 최근의 간단한 스타터 방식!

    • 프로필사진
      Favicon of https://blog.jiniworld.me BlogIcon jiniya222021.05.20 16:23 신고

      그렇네요! 코멘트 감사합니다!
      글을 올릴 당시와 2020년 7월에 `springfox-boot-starter` 가 올라왔었네요!!
      해당 부분은 추가해서 다시 올리겠습니다. 좋은 정보 감사해요!

  • 프로필사진
    샘숭22021.05.11 17:14

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

    -> 바로 밑에 첨부한 짤은 어디서 보는 거에요? (제 크롬 브라우저 네트워크 탭에는 이런 탭의 형태가 아닌데...)

    • 프로필사진
      Favicon of https://blog.jiniworld.me BlogIcon jiniya222021.09.15 15:09 신고

      fiddler 4 라는 툴을 이용하여 조회했습니다.
      https://www.telerik.com/fiddler

1 2 3 4 5 6 7 8 9 ··· 17