[Spring boot] Springdoc-openapi를 통한 Swagger UI 설정

Swagger UI 란

Swagger UI는 RESTful 웹 서비스를 문서화하고 시각적으로 탐색할 수 있게 해주는 오픈 소스 도구입니다. Swagger는 API 설계, 문서화 및 테스트에 사용되는 일련의 도구와 규격을 제공하는 프로젝트의 일부입니다. Swagger UI는 Swagger 스펙에 따라 작성된 API의 인터랙티브한 문서를 생성하며, 사용자는 브라우저에서 API를 쉽게 탐색하고 테스트할 수 있습니다.

Swagger UI의 주요 특징은 다음과 같습니다:

1. 인터랙티브 API 문서화: Swagger UI를 사용하면 API의 엔드포인트, 매개변수, 응답 등을 시각적으로 확인할 수 있습니다. 각 엔드포인트에 대한 설명, 지원되는 HTTP 메소드, 매개변수 및 예상되는 응답 형식이 자세히 표시됩니다.

2. API 테스트 기능: Swagger UI는 API를 직접 테스트할 수 있는 기능을 제공합니다. 사용자는 특정 엔드포인트에 대한 요청을 시뮬레이션하고 실제로 데이터를 보내고 응답을 확인할 수 있습니다.

3. 다양한 언어 및 프레임워크 지원: Swagger는 여러 가지 언어 및 프레임워크에서 사용될 수 있는 스펙으로 정의되어 있으므로, Swagger UI를 사용하여 다양한 언어와 프레임워크로 개발된 API를 문서화할 수 있습니다.

4. 사용자 정의 가능한 테마: Swagger UI는 테마를 사용하여 외관을 사용자 정의할 수 있습니다. 이를 통해 문서의 디자인을 애플리케이션 또는 회사의 스타일에 맞게 조정할 수 있습니다.

 

springdoc-openapi 란

springdoc-openapi는 Spring Framework 기반의 RESTful API 프로젝트에서 OpenAPI(이전에는 Swagger라고도 불림) 문서를 생성하기 위한 도구입니다. Spring Boot 애플리케이션에서 OpenAPI 스펙을 자동으로 생성하고 문서화하는 데 도움이 됩니다.

주요 특징과 장점은 다음과 같습니다:

1.자동 문서 생성: springdoc-openapi는 API의 컨트롤러, 모델 및 기타 구성 요소를 분석하여 자동으로 OpenAPI 문서를 생성합니다. 이를 통해 개발자는 API 변경 사항에 따라 수동으로 문서를 유지 관리할 필요가 없습니다.

2. Swagger UI 통합: springdoc-openapi는 Swagger UI를 통합하여 생성된 OpenAPI 문서를 시각적으로 표시하고 사용자가 API를 테스트하고 이해할 수 있는 간편한 환경을 제공합니다.

3. 다양한 설정 옵션: 다양한 설정 옵션을 제공하여 OpenAPI 문서의 내용과 형식을 사용자 지정할 수 있습니다. 이를 통해 필요에 따라 문서를 조정하고 프로젝트의 요구 사항에 맞게 설정할 수 있습니다.

4. 스프링 애너테이션 지원: springdoc-openapi는 스프링 프레임워크의 애너테이션을 지원하여 코드에 직접 OpenAPI 정보를 포함시킬 수 있습니다. 이를 통해 더욱 세밀한 제어가 가능합니다.

 

springdoc-openapi 사용

저는 spring boot 3.x 버전에서 springdoc-openapi를 설정하였습니다.

우선 build.gradle 파일에 dependency를 추가해줍니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

 

 

해당 dependency를 추가해주는것만으로 Swagger UI에 접근할 수 있습니다.

http://server:port/swagger-ui.html 에 접속하면 아래와 같이 API 목록을 확인할 수 있습니다.

 

applicatioin.yml 파일에 springdoc 속성을 추가해 Swagger 문서의 노출을 설정할 수 있습니다.

추가적인 속성들은 공식사이트에서 확인가능합니다.

springdoc:
  swagger-ui:
    # 각 API의 그룹 표시 순서
    # path, query, body, response 순으로 출력
    groups-order: DESC

    # 태그 정렬 순서.
    # alpha: 알파벳 순 정렬
    tags-sorter: alpha

    # 컨트롤러 정렬 순서.
    # method는 delete - get - patch - post - put 순으로 정렬된다.
    operations-sorter: method

    # swagger-ui default url인 petstore html의 비활성화 설정
    disable-swagger-default-url: true
    
    # swagger-ui에서 try 했을 때 request duration을 알려주는 설정
    display-request-duration: true

 

 

Controller에 tag annotatation을 추가해서 Tag 단위로 가독성이 좋게 노출할 수 있습니다.

@Controller
@RequiredArgsConstructor
@Tag(name = "TravelController", description = "TravelController API 목록")
public class TravelController {

 

참고자료

https://hogwart-scholars.tistory.com/entry/Spring-Boot-SpringDoc%EA%B3%BC-Swagger%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%B4-API-%EB%AC%B8%EC%84%9C%ED%99%94-%EC%9E%90%EB%8F%99%ED%99%94%ED%95%98%EA%B8%B0#SpringDoc-1

https://springdoc.org/