현재 진행 중인 REST API 프로젝트에 문서화를 적용하려고 하는데 API 문서를 간단하게 자동화할 수 있는 도구 중 하나가 바로 Swagger이다.
스웨거(Swagger)란?
RESTful API를 설계, 빌드, 문서화, 사용하기 위한 오픈 소스 프레임워크이며
API 문서를 자동으로 생성해주고 개발자는 이를 통해 API를 쉽게 테스트할 수 있다
무엇보다 스웨거를 사용하면 API의 모든 세부 사항을 명확히 정의할 수 있어, 협업 시 API에 대한 오해를 줄이고 개발 속도를 높일 수 있다.
현재 프로젝트 만들면서 작성하고 있는 버전이 Spring boot 3.0 이상이고 기존에 사용했던 springfox은 20년 7월 이후로 업데이트가 되지 않고 있다고 하니 버전은 24.08.23일 작성기준으로 최신버전인 springdoc-openapi-ui 라이브러리를 사용해야한다고 한다.
1. springdoc-openapi-ui를 적용시켜보기
일단 1.7.0 버전이 그나마 많이 사용하고 있으니까 저 버전으로 사용해보겠습니다
물론, 다른 버전을 사용하고 싶다면 아래 링크에서 안정된 버전으로 확인해볼 수 있다.
https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
1.1 의존성 적용시키기
프로젝트에 springdoc-openapi-ui를 적용하려면, 먼저 Maven 또는 Gradle에 다음과 같은 의존성을 추가해야한다.
Maven을 사용하는 경우:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.7.0</version>
</dependency>Gradle을 사용하는 경우:
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'1.2 프로젝트 내 Controller에 사용해보기
이렇게 클래스 단과 메서드 단에 Swagger 애너테이션을 적용했는데 대표적으로 몇 가지만 함께 보겠습니다
-
@Tag
역할: API의 그룹을 정의하여, 특정 컨트롤러에 속하는 API 엔드포인트들을 설명하는 태그를 생성합니다.
위치: 클래스 레벨에서 사용합니다. -
@Operation
역할: 특정 API 엔드포인트에 대한 세부 정보를 정의합니다. 이 애너테이션을 통해 엔드포인트의 설명, 요청 및 응답의 상세 내용을 문서화할 수 있습니다.
위치: 메서드 레벨에서 사용됩니다. -
@Parameter
역할: API 엔드포인트의 파라미터에 대한 설명을 제공합니다. 각 파라미터의 타입, 위치, 설명 등을 문서화하는 데 사용됩니다.
위치: 메서드 파라미터 앞에서 사용됩니다.
위에 소개한 메서드들 바탕으로 추가시켜 적용시켜봤습니다.
2.나의 Swagger 문서 확인해보기
http://localhost:8080/swagger-ui/index.html 기본적으로 포트번호를 변경하지 않았다면 8080으로 잘 들어가지는 것을 확인할 수 있다 앞으로 RestApi로 작성했을때 테스트를 해당 메서드를 눌러 쉽게 테스트 해볼 수 있다.
