[SpringBoot] OpenAPI 3.0 설정하기! (swagger-ui)

# OpenAPI 3.0 example code (swagger-ui)

 swagger가 3.0으로 업데이트 되면서 명칭도 바뀌고 어노테이션도 바뀌었다. 

그래서 한번 해보는 OpenAPI 3.0 설정하기!

 

https://hjho95.tistory.com/39 는 OpenAPI를 사용하기 위한 설정.

https://hjho95.tistory.com/40 은 Annotation을 이용한 Document작성.

https://hjho95.tistory.com/41 은 ApiResponse의 ref 구현.

 

Unable to render this definition Error 해결 맨 밑에 있음.

# Refference

document: https://springdoc.org

example-ui: http://158.101.191.70:8081/swagger-ui/index.html

github: https://github.com/springdoc/springdoc-openapi-demos/blob/master/springdoc-openapi-spring-boot-2-webmvc/src/main/java/org/springdoc/demo/app2/Application.java

# 환경

Tool  : STS 4.13.0
Ver   : 2.7.5 [GA]
JDK   : 11
Repo  : MAVEN
DB    : ORACLE XE (11g), PostgreSQL (14)
View  : Thymeleaf
jQuery: 3.6.0

# pom.xml

<!-- Spring Document -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.13</version>
</dependency>

이전에는 io.springfox의 springfox-swagger-ui, springfox-swagger2 메이븐을 설정했었음. 

하나로 통합한 듯 하다.

# application.yml

springdoc: 
  packages-to-scan: com.prjt.blog.main, com.prjt.blog.sub #, com.prjt.blog.test
  packages-to-exclude: com.prjt.blog.sub.controller 
  paths-to-match: /api-v1/**
  paths-to-exclude: /api-v1/common/voca/**
  swagger-ui:
    path: /document #default: /swagger-ui.html
    # {domain}/document 입력 시 /swagger-ui/index.html로 이동함.
  api-docs: 
    path: /api-document #default: /v3/api-docs
    enabled: true

properties 설명 참조 페이지: https://springdoc.org/#properties

설정을 하지 않더라도 동작은 함.

# Configuration

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                  .info(
                          new Info().title("[Dev] Document (blog-api)")
                                  .description("블로그 API 서버 문서")
                                  .version("1.0.0")
                                  .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                  )
                  .externalDocs(
                          new ExternalDocumentation()
                                  .description("Github")
                                  .url("https://github.com/springdoc/springdoc-openapi-demos/blob/master/springdoc-openapi-spring-boot-2-webmvc/src/main/java/org/springdoc/demo/app2/Application.java")
                  );
    }
}

# page

application.yml의 springdoc.swagger-ui.path 로 지정한 /document로 {host}/document 페이지 진입하면 자동으로 {host}/swagger-ui/index.html 로 이동한다. default는 "http://server:port/context-path/swagger-ui.html" 임

# Unable to render this definition Error

Unable to render this definition

The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

 

처음 기동 시 해당 에러가 났는데, 이유가 "/v3/api-docs" 의 응답이 json string으로 나감.

필자는 ResponseBodyAdvice<Object> 를 implements 하여 오브젝트 형식으로 응답이 나갔어야 했음.

jsonString 형식의 응답을 Map 형식으로 형 변환 후 응답을 주니 정상적으로 작동함.

# 내용

 swagger-ui의 설정은 이게 끝이 아니다. 이제 시작이라고 볼 수 있는,,,,

이제 Controller, Controller의 메소드, VO, VO 필드 하나하나 어노테이션을 달아줘야 조금 더 이쁘고, Swagger만으로 확인 가능한 Document를 작성할 수 있다.

 해당 내용은 아래 2에서 작성할꺼임.

 

https://hjho95.tistory.com/40 은 Annotation을 이용한 Document작성.

[SpringBoot] OpenAPI 3.0 example code - 2 (swagger-ui)