Springdoc OpenAPI(3) - 기본 설정

이번 포스트에서는 지난번 포스트에 이어서 Springdoc의 기본적인 설정들에 대해 알아보겠다.
Swagger 화면상에 나타날 부분들을 설정해 주는 Configuration 부분과 Swagger의 경로 등을 설정해 주는 application 설정 부분으로 나눠보았다.

Configuration

공식 문서(config)
공식 문서를 찾아보니 화면에 나타날 제목과 문서 버전 등을 Configuration을 통해 설정하는 것을 알 수 있었다.
다음과 같이 OpenAPI를 Bean으로 등록할 수 있다.
Info를 통해 제목, 버전, 설명, 라이센스 등을 표시할 수 있고, 외부 문서가 있는 경우 externalDoc를 통해 보여줄 수 있다.

예시 코드

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("테스트 Swagger API 문서")
                        .version("1.0")
                        .description("Velog 포스팅을 위한 스웨거 API 문서입니다.")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                )
                .externalDocs(new ExternalDocumentation()
                        .description("Velog 블로그")
                        .url("https://velog.io/@donggyu/posts")
                );
    }
}

예시 화면

---

application

공식 문서(properties)
.yaml이나 .properties 파일을 통해 Swagger의 경로나 활성화 여부 등을 설정해 줄 수 있다.
Swagger를 직접 실무에서 사용해 봤을 때는 default 설정만으로도 충분해서 크게 건드린 건 없었던 것 같다.

사용했던 설정들과 사용하면 좋을 것 같은 설정 몇 개 정도만 간단하게 적고 넘어간다.

springdoc.api-docs.path

• Json 포맷의 Swagger 문서 경로
• default : /v3/api-docs

springdoc.api-docs.enabled

• Swagger 문서의 활성화 여부
• false일 경우 Swagger UI도 비활성화됨
• Swagger 문서를 product server에서 비공개하고 싶은 경우 false로 해서 사용
• default : true

springdoc.swagger-ui.path

• Swagger UI 경로
• default : /swagger-ui.html

springdoc.swagger-ui.filter

• Swagger UI에서 tag를 필터링(검색)할 수 있는 상자가 생김
• default : false

springdoc.swagger-ui.operationsSorter

• operation 을 정렬
• alpha(사전순), method(HTTP method), a function

springdoc.swagger-ui.tagsSorter

• tag를 정렬
• alpha(사전순), a function

springdoc.default-consumes-media-type

• 모든 API의 기본 요청(Request) Content-Type 지정
• default : application/json

springdoc.default-produces-media-type

• 모든 API의 기본 응답(Response) Content-Type 지정
• default : /

참고 문서

Springdoc 공식 문서

---

다음 포스트에서는 Springdoc에서 API들을 그룹화할 수 있는 방법에 대해 알아보겠다.

잘못된 정보나 추가할 내용이 있다면 언제든지 댓글로 알려주세요! 여러분의 피드백은 더 좋은 글을 만드는 데 큰 도움이 됩니다. 😊