[Spring Data JPA Tutorial] 8. Swagger를 이용한 REST API 자동 문서화 (OpenAPI 3)

1. Swagger
   1. OpenAPI 3
   2. Swagger-ui
2. 설정
   1. 의존성 라이브러리 추가
   2. 프로퍼티 설정 (operations-sorter, display-query-params-without-oauth2)
3. Swagger-ui 실행
   1. /swagger-ui/index.html
   2. OpenAPI Info 설정
   3. 실행

---

1. Swagger

1.1. OpenAPI 3 (OAS 3)

OpenAPI Specification는 RESTful 웹서비스 API를 시각적으로 표현할수 있도록 정한 명세입니다.
가장 최신 명세는 OpenAPI 3고, 정해진 규칙에 맞춰 작성된 명세는 Swagger UI로 웹문서화할 수 있습니다.

API 스펙은 json 나 yaml 형식으로 표현할 수 있습니다.

아래의 사진은 springdoc-openapi 를 이용하여 자동생성된 Open API 명세의 예시입니다.

1.2. Swagger-ui

Swagger는 OpenAPI 명세에 맞춰 작성된 문서를 이용하여 api를 자동으로 웹문서화 해주는 오픈소스 프레임워크입니다.

이전에 api를 문서화를 직접 하기 위해서는 api가 수정될 때마다 매번 작업을 해야한다는 번거로움이 있었다면,
Swagger를 설정할 경우, 간단한 설정만으로 자동으로 문서화 해주니 매우 편리합니다.

Swagger-ui 페이지 화면

Spring Boot 2에서 생성한 REST API에 대한 OpenAPI 3 문서화를 하고, 이를 이용하여 Swagger-ui 화면을 만들어 주는 라이브러리들이 몇가지 있는데

그 중, 우리는 springdoc-openapi 라이브러리를 이용하여 설정을 진행할 예정입니다.

springdoc-openapi 라이브러리는 아래의 항목들을 지원합니다.

• OpenAPI 3
• Spring Boot 1, Spring Boot 2
• JSR-303 (ex. @NotNull, @Min, @Max, @Size)
• Swagger-ui
• OAuth 2

---

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. 프로퍼티 설정

Swagger-ui에서 사용할 OpenAPI 3.0 생성 규칙을 프로퍼티에 설정할 수 있습니다.

설정 할 수 있는 정보로는 아래와 같은 정보들이 있습니다.

• request/response의 Media Type 기본 값
• tag(api 묶음) 나 operation(api)의 정렬 방법
• 자동으로 문서화할 api path 등을 설정할 수 있습니다.

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: /
    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문서를 호출합니다.

---

3. Swagger-ui 실행

3.1. /swagger-ui/index.html

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

프로퍼티상에서, Swagger-ui 경로를 /로 지정했기때문에, http://localhost:8989 로 접근하면 바로 http://localhost:8989/swagger-ui/index.html로 redirect 됩니다.

아래는 Fiddler Classic을 이용해 조회한 결과로, 302 Http Status Code로, 페이지가 이동이 되었고, Location 값이 /swagger-ui/index.html 로 나오는 것을 확인할 수 있습니다.

궁극적인 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. OpenAPI Info 설정

OpenAPI 의 Info 설정을 별도하지 않아도, springdoc-openapi 라이브러리는 기본적인 Swagger-ui 설정을 제공해줍니다.

Swagger-ui 기본 화면

만약, Swagger-ui 화면에서 문구를 변경하고 싶다면, OpenAPI bean의 Info에 설정해주면 됩니다.

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 Data JPA Tutorial")
                .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.3. 실행

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

※ GitHub에서 demo 프로젝트(v1.0.4)를 다운받아 볼 수 있습니다.

---

+++ keyword

• io.swagger.core.v3 설정하기
• OpenAPI 3.0 + Swagger
• Spring Boot에 OpenAPI 3 설정하기
• Documenting RESTful API with Swagger 3 + springdoc-openapi