[Spring] 스웨거 (Swagger) v3 설정하기

2.설정

https://springdoc.org/#properties

OpenAPI 3 Library for spring-boot

1) build.gralde에 관련 의존성 추가

dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
}

2) yml 설정 추가

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  display-query-params-without-oauth2: true
  paths-to-match:
    - /v1/**

• 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 리스트

operations-sorter 설정에 따른 api 출력화면

springdoc.swagger-ui.operations-sorter : alpha

springdoc.swagger-ui.operations-sorter : method
DELETE → GET → PATCH → POST → PUT 순서

3) SwaggerConfig 설정 등록

// SwaggerConfig.java
@OpenAPIDefinition(
        info = @Info(title = " API 명세서",
                description = "멤버 서비스 API 명세서",
                version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {
 
    @Bean
    public GroupedOpenApi memberOpenApi() {
        String[] paths = {"/v1/**"};
 
        return GroupedOpenApi.builder()
                .group("멤버 서비스 API v1")
                .pathsToMatch(paths)
                .build();
    }
}

4) security 설정

5) 컨트롤러에 적용

[Spring] 스웨거 (Swagger) 설정하기

확인

---

연관된 글 :

[Spring] Swagger 어노테이션

[Spring] 스웨거 (Swagger) 설정하기

스웨거 Swagger

 

참고:

SpringBoot SpringDoc(OpenAPI)을 이용한 Swagger 적용

[Spring Boot Tutorial] 13. OpenAPI 3.0를 이용한 REST API 문서 만들기 (Swagger v3)

[Swagger] Open API 3.0 그리고 Swagger v3

Spring boot Swagger 3.0 적용하기