REST API를 문서화하는 것은 외부 기관이나 조직 내 다른 팀(예: UI 팀, 모바일 애플리케이션 팀)이 API를 소비할 때 필수적입니다. 문서화를 통해 다음과 같은 질문에 답할 수 있습니다:
요청 형식은 무엇인가?
응답 형식은 무엇인가?
어떤 유효성 검사가 적용되어 있는가?
이러한 질문에 대해 매번 설명하는 대신, API 문서를 제공하여 시간을 절약하고 혼란을 줄일 수 있습니다.
OpenAPI는 HTTP API를 문서화하기 위한 표준을 제공하는 오픈 소스 커뮤니티입니다. Spring Doc OpenAPI 라이브러리를 사용하면, Spring Boot 애플리케이션에서 자동으로 API 문서를 생성할 수 있습니다.
Spring Doc OpenAPI 의존성 추가
gradle 파일에 Spring Doc OpenAPI 의존성을 추가하여 REST API 문서화를 설정합니다.
버전에 따라 의존성을 조정해야 합니다. 예를 들어, Spring Boot 2.x 버전을 사용하는 경우, springdoc-openapi-ui의 다른 버전을 사용할 수 있습니다.
애플리케이션 재시작 및 Swagger UI 확인
의존성을 추가한 후 애플리케이션을 재시작하고, http://localhost:8080/swagger-ui/index.html에 접속하여 Swagger UI를 통해 자동으로 생성된 REST API 문서를 확인할 수 있습니다.
Swagger UI는 다음과 같은 정보를 제공합니다:
- API 경로 및 HTTP 메서드: 각 API 엔드포인트의 경로와 지원하는 HTTP 메서드(GET, POST, PUT, DELETE 등)를 보여줍니다.
- 요청 및 응답 형식: 요청으로 전달할 JSON 데이터의 구조와 응답 형식을 설명합니다.
- 유효성 검사: 각 필드에 적용된 유효성 검사를 문서화하여, 클라이언트가 어떤 데이터 형식이 요구되는지 이해할 수 있습니다.
API 문서 내용 확인
Swagger UI를 통해 API 문서에 포함된 내용을 확인할 수 있습니다:
- 요청 형식: 각 엔드포인트에서 요구하는 JSON 형식 및 필수 필드가 표시됩니다.
- 응답 형식: 성공 또는 실패 시 반환되는 JSON 데이터의 형식이 문서화됩니다.
- 유효성 검사: 필드에 적용된 @NotEmpty, @Size, @Pattern 등의 애노테이션 정보를 기반으로 각 필드의 유효성 검사가 설명됩니다.
Swagger UI를 통해 직접 API를 테스트해볼 수도 있습니다. 예를 들어, "Try it out" 옵션을 사용하여 API 호출을 실행하고, 실제 응답을 확인할 수 있습니다.
추가 문서화 및 개선
기본 문서화를 설정한 후, Spring Doc OpenAPI 라이브러리가 제공하는 애노테이션을 활용하여 문서의 가독성을 향상시킬 수 있습니다. 예를 들어, 예제 데이터를 추가하여 클라이언트가 API 사용 방법을 더 쉽게 이해할 수 있도록 할 수 있습니다.
