SpringDoc 이란? 그리고 적용방법

SpringDoc

SpringDoc는 Spring Framework를 기반으로 한 오픈 소스 프로젝트로서, Swagger UI를 자동으로 생성하여 Spring Boot 애플리케이션의 API 문서화를 도와주는 도구입니다. Swagger를 사용하여 API 문서를 작성하고 노출시키는 작업을 자동화하여 개발자가 더욱 간편하게 REST API를 문서화할 수 있도록 지원합니다.

SpringDoc는 Swagger 스펙(OpenAPI 스펙)을 기반으로 자동으로 API 문서를 생성합니다. Spring 애너테이션을 사용하여 API 엔드포인트, 요청 및 응답 형식, 매개변수 등을 정의하면 SpringDoc가 이 정보를 수집하여 Swagger UI를 생성합니다.

Spring Doc 기능과 특징

1. 자동 문서 생성: SpringDoc는 Spring 애너테이션을 분석하여 API 문서를 자동으로 생성합니다. 개발자는 코드에 애너테이션을 추가함으로써 API의 작동 방식과 응답 형식을 정의할 수 있습니다.

2. Swagger UI 지원: SpringDoc는 Swagger UI를 사용하여 생성된 API 문서를 시각적으로 표시합니다. Swagger UI는 사용자가 API 엔드포인트를 쉽게 탐색하고 테스트할 수 있는 인터페이스를 제공합니다.

3. OpenAPI 스펙 지원: SpringDoc는 OpenAPI 스펙(이전에는 Swagger 스펙으로 알려졌음)을 준수합니다. 따라서 SpringDoc를 사용하여 생성된 API 문서는 표준화된 형식을 따르며, 다른 도구 및 플랫폼에서도 호환됩니다.

4. 다양한 설정 옵션: SpringDoc는 다양한 설정 옵션을 제공하여 API 문서의 모양과 동작을 사용자 정의할 수 있습니다. 예를 들어, 문서에 보여질 엔드포인트를 선택하거나, 인증 설정을 구성하는 등의 작업이 가능합니다.

SpringDoc는 개발자가 Spring Boot 애플리케이션의 API를 간편하게 문서화할 수 있도록 도와주는 강력한 도구입니다. API 문서의 작성과 유지보수를 자동화하여 개발자의 생산성을 향상시키고, 팀 간의 협업을 강화하는 데 도움을 줍니다.

Spring Doc 적용

build.gradle

implementation 'org.springdoc:springdoc-openapi-ui:1.6.12'

application.yml

springdoc:
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /swagger-ui.html
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true

위 코드를 2개의 파일에 추가해줍니다.

http://localhost:8081/swagger-ui/index.html

위 URL로 접근하게 되면

이렇게 Doc가 자동으로 생성이 됩니다.