OpenAPI 3.0을 이용한 Spring REST API 문서화

1. 개요

• 라이브러리가 OpenAPI 3.0 스펙에 맞는 JSON을 자동으로 만들어 주면, Swagger UI는 만들어진 JSON을 바탕으로 화면에 표시 해줍니다.
• Spring Boot 2.0.9.RELEASE로 테스트 하였습니다.

 

2. 문제 해결

• messageconverter가 설정되어 있어서 Swagger UI가 /v3/api-docs/ end-point로 접근시 String으로 감싼 JSON 형으로 리턴됨.
  1. HttpServletRequest 객체의 getRequestURI 메소드를 사용하여 요청한 Uri를 가져옴.
  2. Uri가 /v3/api-docs/ 또는 /v3/api-docs/swagger-config 인지 확인하여 원본 내용을 리턴하게 예외처리. (e.g. json이면 json으로)

 

3. build.gradle 파일에 dependency 추가

dependencies {
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.2.30'
}

 

4. 설정 파일에 관련 설정 추가

springdoc:
  api-docs:
    groups:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html
    displayRequestDuration: true
    groups-order: DESC

 

5. OpenApiConfig.java 파일 작성

package kr.webgori.lolien.discord.bot.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
    info = @Info(title = "lolien-discord-bot API 명세서",
        description = "API 명세서",
        version = "v1",
        contact = @Contact(name = "webgori", email = "webgori@gmail.com"),
        license = @License(name = "Apache 2.0",
            url = "http://www.apache.org/licenses/LICENSE-2.0.html")
    )
)
@Configuration
public class OpenApiConfig {
  /**
   * customGameOpenApi.
   * @return GroupedOpenApi
   */
  @Bean
  public GroupedOpenApi customGameOpenApi() {
    String[] paths = {"/custom-game/**"};
    return GroupedOpenApi.builder().setGroup("내전 관련 API").pathsToMatch(paths)
        .build();
  }

  /**
   * leagueOpenApi.
   * @return GroupedOpenApi
   */
  @Bean
  public GroupedOpenApi leagueOpenApi() {
    String[] paths = {"/league/**"};
    return GroupedOpenApi.builder().setGroup("리그 관련 API").pathsToMatch(paths)
        .build();
  }
}

 

6. Swagger UI 확인

http://IP 또는 도메인:포트/swagger-ui.html 으로 접속 후 확인