[Spring Boot] Automatically generate OpenAPI3 documentation with Kotlin and Spring Boot 3

현재 Spring Boot3에서 Swagger3 미지원 상태이다.
여기 사용된 버전은 jdk 17, Spring Boot3.0.2, Open Api3이다

Add to Library

open api3 구축과 swagger-ui를 사용하기 위한 라이브러리를 추가한다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

스프링에서 사용할 수 있도록 컨피그 세팅도 다하고 서버 실행 후에 No mapping for GET /swagger-ui/index.html 가 확인되었다.

경로 매핑을 안해줘서 그런가 싶어서 찾아보다가 보게된 내용이다.

Springfox Type javax.servlet.http.HttpServletRequest not present

확인결과 부트3에서는 현재 스웨거3를 지원 안한다🥲

그래서 답변에서 알려주는대로 Springdocs 공식문서를 참고해서 세팅을 시작했다.

springdoc-openapi v2.0.4

OpenAPI와 Swagger 구조

레퍼런스에서 openAPI와 스웨거가 스프링부트에서 어떤식으로 동작하는지에 대해서 구조적으로 알려준다.

오픈api에서 다양한 라이브러리를 지원하는데 거기서 사용하려는 항목만 가져와서 설정하면된다.

swagger-ui를 사용할 것이기 때문에 관련 항목을 추가해줬다.

<!-- 스웨거ui를 표현하고자 할 때 이 종속성을 추가하면 된다 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>${org.springdocs}</version>
</dependency>

<!-- 확인해보니 이 라이브러리는 스웨거 사용안하고 쓰려는 목적일 때 적합해서 제거했다. -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
	<version>${org.springdocs}</version>
</dependency>

<!-- 코틀린을 쓰려는 프로젝트에서 이 종속성을 추가하면 코틀린에 필요한 종속성을 지원해준다. -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-common</artifactId>
	<version>${org.springdocs}</version>
</dependency>

스프링 부트 설정 추가

스프링 부트에서 사용할 수 있도록 openAPI와 스웨거 관련 설정을 추가한다.

// 코드단에서 처리도 가능하고, yml이나 properties파일에서도 설정을 할 수 있다.
   @Bean
    fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
        config.showCommonExtensions = true
        config.queryConfigEnabled = true // 레퍼런스 확인 결과 xss 보안문제가 있어서 4.1.12? 버전 이상부터는 막혀있는데 이전 버전에서는 비활성화하는걸로 권장해서 제거함, 쿼리 파라미터로 스웨거 관련 설정하는데 사용되는 정보임
        config.isEnabled = false //openapi 비활성화함
        config.isDisableSwaggerDefaultUrl = true // 기본경로 '/swagger-ui/index.html' 경로 막음
        config.isUseRootPath = false // 최상단경로 사용 비활성화
        return config
    }

// 스웨거에 표기할 항목을 설정한다.
    @Bean
    fun appApi(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("Drill's Project")
            .pathsToMatch("/**")
            .build()
    }

 

application.yml 설정

# 코드단에서 미지원하는건지 확인해봐야함, 원래는 되는 항목인데 못찾은걸수도 있다.
springdoc:
  api-docs:
    enabled:false ## 이 설정은 사용자가 커스텀한 Bean 사용을 활성화 시키는 옵션이다. 기본값으로는 true라서 Bean설정을 한 경우라면 별도로 추가 안해도됨
  packages-to-scan: com.drills.backend.controller // 지정된 경로 안의 모든 api정보가 표기됨, 설정정보만 표기될 수 있게 변경 필요함
  swagger-ui:
    path: /drills-swagger.html #스웨거 접근 경로 설정을 별도로 함
  api-docs:
    path: /drills/v3/api-docs #host:port/v3/api-docs로 접근하면 openapi 정보를 다 확인할 수 있어서 비활성화 하려고 했는데 비활성화 설정이 안돼서 기본경로를 변경함

# 코드단에서도 동일하게 설정가능함
#  swagger-ui:
#    enabled: false
#  use-management-port: true

 

이렇게 세팅하고 실행하면 스웨거 경로에 접근할 수 없다. 경로 세팅을 따로 해야한다.

@Configuration
class WebConfiguration : WebMvcConfigurer {
    override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
        registry.addResourceHandler("/drills-swagger.html")
            .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/4.15.5/")
    }
}

경로 세팅에 스웨거 버전을 써줘야 하는데 이 버전은 메이븐이나 그래들 디펜던시 추가된 항목에서 확인할 수 있다.

위와 같이 설정을 하면 https://host/swagger-ui/index.html과 https://host/v3/api-docs로 접근할 수 없고, 지정한 경로로 접근해야 확인 가능해진다.

API 문서 공개를 굳이 해야하는게 아니라면 경로를 막아두는 것이 좋다.