- RESTful 웹 서비스를 설계, 구축, 문서화 및 사용할 수 있는 오픈 소스 소프트웨어 프레임워크를 의미합니다. - 이를 통해 API의 구조와 동작을 정의하기 위한 도구와 사양 세트를 제공하여 API를 개발하고 유지하는 것을 더욱 쉽게 만들어줍니다. API의 엔드포인트, 매개변수, 응답 등을 정의하고 문서화할 수 있습니다.
- 어노테이션을 기반으로 작동하고 사용이 되며 API의 구조와 동작에 대해 정의를 합니다. 또한 Swagger를 이용하기 위해서는 라이브러리인 SpringFox나 SpringDoc OpenAPI를 사용해야 합니다. - Rest API에서 설계 과정 중 'API 문서화 단계'에서 이를 사용합니다.
- 기존에 접속이 잘 되던 Swagger-ui를 Spring Boot 3.x 버전으로 마이그레이션 함에 따라서 경로를 찾지 못하는 오류(404)가 발생함을 확인하였습니다.
💡공식사이트에 접속
- 아래와 같이 springdoc-openapi v1.8.0 최신 버전의 경우 공식 사이트에서 아래와 같이 이야기하고 있습니다.
💡springdoc-openapi v1.8.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x. An extended support for springdoc-openapi v1 project is now available for organizations that need support beyond 2023. For more details, feel free to reach out: sales@springdoc.org
- springdoc-openapi v1.8.0의 경우 Boot 2.x 및 1.x를 지원하는 최신 오픈 소스 릴리스입니다. 2023년 이후에도 지원이 필요한 조직을 위해 springdoc-openapi v1 프로젝트에 대한 확장 지원이 이제 제공됩니다. 자세한 내용은 sales@springdoc.org로 문의하세요.
https://springdoc.org/#getting-started
2. 해결 방법
💡해결 방법
- 아래와 같이 springdoc-openapi-starter-webmvc-ui 라이브러리를 사용하기를 권장하고 있습니다.
- Spring, Spring Boot 환경에서 적용이 되었던 Swagger 라이브러리의 종류들을 확인하고, 각각 적용이 가능한 버전들에 대해서 알아봅니다.
라이브러리
특징
Spring Boot 호환성
OpenAPI 버전
SpringFox Swagger2
- Spring 기반 애플리케이션용 - 자동 Swagger 2.0 문서 생성 - 최근 업데이트 중단
Spring Boot 2.x까지
Swagger2
SpringDoc OpenAPI UI
- Spring Boot 애플리케이션용 - 자동 OpenAPI 3 문서 생성 - 활발한 유지보수
Spring Boot 1.x, 2.x
Swagger3
SpringDoc OpenAPI Starter WebMVC UI
- Spring Boot 3.x용 - WebMVC 애플리케이션 지원 - Swagger UI 통합
Spring Boot 3.x
Swagger3
[ 더 알아보기] 💡 Swagger와 Swagger 라이브러리의 차이점은 무엇일까?
- Swagger: API 설계, 문서화, 테스트를 위한 오픈소스 프레임워크 및 사양을 의미합니다. - Swagger 라이브러리: Swagger 사양을 구현하고 애플리케이션에 통합하기 위한 도구를 의미합니다.
- 즉, Swagger는 개념과 사양을 정의하고, Swagger 라이브러리는 이를 실제로 구현하여 개발자가 쉽게 사용할 수 있게 해주는 도구입니다.
1. SpringFox Swagger2
💡SpringFox Swagger2
- Spring 기반 애플리케이션에서 Swagger 2.0 문서를 자동으로 생성하기 위한 라이브러리를 의미합니다. - SpringFox Swagger2는 최근 업데이트가 2020년 이후 중단되어 Spring Boot 3.x 버전과 호환성 문제가 있을 수 있습니다. 따라서 최신 프로젝트에서는 SpringDoc OpenAPI를 사용하는 것이 권장됩니다.
💡SpringDoc OpenAPI UI - Spring Boot 애플리케이션에서 OpenAPI 3 (이전의 Swagger) 문서를 자동으로 생성하기 위한 라이브러리입니다. - 해당 라이브러리의 경우 Spring Boot 2.x 및 1.x에 대해서 지원하는 라이브러리입니다. 즉, 최신 Spring Boot 3.x 버전을 사용하는 경우 지원을 하지 않습니다.
💡 SpringDoc OpenAPI Starter WebMVC UI - Spring Boot 3.x 버전과 호환되는 OpenAPI (Swagger) 문서 생성 라이브러리입니다. - Spring Boot 3.x에서 WebMVC 애플리케이션을 위한 OpenAPI 3 (Swagger) 지원을 제공합니다. - 자동으로 API 문서를 생성하고 Swagger UI를 통해 시각화합니다.
- Swagger로 구성하는 API 문서의 제목, 버전, 설명에 대해서 설정합니다. - 즉, "데모 프로젝트 API Document"라는 제목, "v0.0.1" 버전, 그리고 "데모 프로젝트의 API 명세서입니다."라는 설명을 가진 API 문서를 생성합니다.
package com.adjh.springboot3tierform.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Swagger springdoc-ui 구성 파일
*/@ConfigurationpublicclassOpenApiConfig{
@Beanpublic OpenAPI openAPI(){
Info info = new Info()
.title("데모 프로젝트 API Document")
.version("v0.0.1")
.description("데모 프로젝트의 API 명세서입니다.").
returnnew OpenAPI()
.components(new Components())
.info(info);
}
}
4. application.properties 파일 지정
💡application.properties 파일 지정
- SpringDoc OpenAPI Starter WebMVC UI를 구성하기 위한 환경 파일입니다.
# Swagger springdoc-ui Configurationspringdoc:packages-to-scan:com.adjh.springboot3tierformdefault-consumes-media-type:application/json;charset=UTF-8default-produces-media-type:application/json;charset=UTF-8cache:disabled:true# 캐시 사용 여부api-docs:path:/api-docs/jsongroups:enabled:trueswagger-ui:enabled:true# Swagger UI 사용여부 : 접근 경로 => <http://localhost:8080/swagger-ui/index.html>path:/demo-ui.html# Swagger UI 추가 접근 경로 => <http://localhost:8080/demo-ui.html>tags-sorter:alpha# alpha: 알파벳 순 태그 정렬, method: HTTP Method 순 정렬operations-sorter:alpha# alpha: 알파벳 순 태그 정렬, method: HTTP Method 순 정렬
💡Swagger 설정에 필요한 주요한 속성들입니다
- 해당 속성들은 일부만 포함하고 있습니다. (* 추가 속성에 대해 궁금하시면 하단의 공식사이트 API Document를 참고하시면 도움이 됩니다)
- REST API Controller 내에서 사용할 수 있는 Swagger Annotation을 적용하여 구성하였습니다.
💡예시에서 사용한 Swagger 주요 어노테이션입니다.
Annotation
설명
@Tag
API 그룹을 정의합니다. 여기서는 "Code-Controller"라는 이름으로 코드 관리 API 엔드포인트를 그룹화했습니다.
@Operation
API 작업의 설명을 제공합니다. 각 메서드에 대한 요약과 상세 설명을 포함합니다.
@ApiResponse
API 응답에 대한 정보를 제공합니다. 응답 코드, 설명, 응답 내용 등을 정의합니다.
@Parameter
API 메서드의 파라미터에 대한 설명을 추가합니다.
@Schema
API 요청 또는 응답의 스키마를 정의합니다. 주로 DTO 클래스에 사용됩니다.
@Hidden
특정 API 엔드포인트를 Swagger 문서에서 숨깁니다.
@SecurityScheme
API 보안 스키마를 정의합니다. 주로 인증 방식(예: JWT)을 설정할 때 사용됩니다.
@SecurityRequirement
특정 API 작업에 보안 요구사항을 적용합니다. @SecurityScheme와 함께 사용하여 인증이 필요한 엔드포인트를 지정합니다.
💡구성 예시 설명
1. @Tag
- 해당 어노테이션을 통해서 Controller에 대한 설명을 작성하였습니다. - name 속성을 통해 Controller 이름을 정의하였고, description 속성을 통해 Controller의 상세 설명을 정의하였습니다.
2. @Operation
- 해당 어노테이션을 통해서 메서드에 대한 설명을 작성하였습니다. - summary 속성을 통해 메서드의 요약 정보를 정의하였고 , description 속성을 통해 메서드의 상세 설명을 정의하였습니다.
3. @ApiResponse
- 해당 어노테이션을 통해 메서드에 대한 API 응답 값을 정의하였습니다. - responseCode 속성을 통해 정상 통신을 하였을 때 받는 응답 코드 값을 정의하고 , description 속성을 통해 통신 응답에 대한 설명을 정의하고, content 속성을 통해 통신 성공 시 정상적 통신일 때 받을 값을 정의하였습니다.
4. @RequestParam @Parameter
- @Parameter 어노테이션을 통해, @RequestParam으로 전달받은 값에 대해서 API 통신에서 파라미터로 전달받을 값에 대해 정의하였습니다. - description 속성을 통해서 파라미터에 대한 상세 설명을 정의하였습니다.
5. @RequestBody @Schema
- @Schema 어노테이션을 통해, @RequestBody으로 전달받을 객체 값에 대해 API 통신에서 받을 값에 대해 정의하였습니다. - implementation 속성을 통해, 전달받을 객체에 대한 상세 정의를 하였습니다.
6. @Hidden
- @Hidden 어노테이션을 통해 Swagger API 정의 내용에서 제외를 하도록 정의하였습니다.
[ Spring Security를 사용하는 경우 ] 7. @SecurityScheme
- 해당 어노테이션을 통해서 Controller를 이용할 때 JWT를 통해서 bearer 인증 방식으로 접근이 가능함을 정의하였습니다. - name 속성을 통해 인증 방식을 정의하고, type 속성을 통해 통신 타입을 지정하였습니다. - scheme 속성을 통해 인증 방식을 정의하고 , bearerFormat 속성을 통해 어떤 인증 방식을 이용할지 정의하였습니다.
8. @SecurityRequirement
- 해당 어노테이션을 통해 메서드에서 인증이 필요함을 정의하였습니다. - 해당 인증으로는 name을 bearerAuth로 지정하여 @SecurityScheme 정의한 name과 매핑이 되도록 구성하였습니다.
