Spring Boot Swagger 3.0 적용 1

Swagger 란 REST APIs를 문서화해주며, APIs를 호출해서 테스트할 수 있게 해주는 OpenAPI 표준이다.

 

Swagger Tool

• Swagger Codegen: Swagger 에 정의된 형태로 Client/Server 코드를 생성하는 CLI 툴
• Swagger UI: Swagger API 명세서를 웹에서 확인 및 테스트할 수 있는 툴
• Swagger Editor: API 설계서/명세서를 작성하기 위한 툴

여기에서는 Swagger UI를 중심으로 작성할 예정이다.

Spring boot 에서는 Swagger를 사용하기 위해 Springfox와 Springdoc-openapi 라이브러리를 사용한다.

Springfox는 2020년 7월 이후로 거의 3년 동안 더이상 업데이트가 진행되지 않고 있고, Springdoc은 최근까지도 활발하게 업데이트가 진행되고 있다. 따라서 Springdoc-openapi를 이용하는 게 더 합리적으로 보인다.

 

Springdoc-openapi

    1. 의존성 설정

Maven
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.15</version>
        </dependency>
        
Gradle
	implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'

   2. application.yml 설정

 

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  api-docs:
    groups:
      enabled: true
  swagger-ui:
    operations-sorter: alpha # alpha(알파벳 오름차순), method(HTTP메소드순)
    tags-sorter: alpha # 태그 정렬 기준
    path: /swagger-ui.html # html 문서 접속 경로
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true
    doc-expansion: none # tag, operation 펼치는 방식
  packages-to-scan: # Swagger 스캔 대상 패키지명
    - com.restwithswagger.controller
  paths-to-match: # requestUri 매칭 패턴
    - /api/rest-template/**

     3. OpenAPI 설정파일 작성

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringShop API")    // API 제목
                        .description("Spring shop sample application")  // API 설명
                        .version("v0.0.1"));	//  API 버전
    }
}

    4. /swagger-ui.html 로 접속해서 화면 확인