Spring Boot에서 Swagger 사용하기

1. Swagger란 무엇인가?

Swagger는  API 문서화 및 테스트를 간편하게 해주는 도구이다 . Swagger는 OpenAPI Specification(OAS)을 기반으로 하며, API의 엔드포인트, 요청/응답 형식 등을 정의하고 문서화하는 데 도움을 준다. 이를 통해 클라이언트와 서버 간의 통신을 명확하게 정의할 수 있다.

2. Spring Boot 3.x.x에서 Swagger 설정하기

Spring Boot 3.x.x에서는 Swagger를 지원하는 springdoc-openapi-starter-webmvc-ui를 사용해야한다.

💡springdoc-openapi의 웹 MVC 통합과 Swagger UI를 포함하는 스타터이다. 이 패키지는 OpenAPI 3.x 스펙을 기반으로 API 문서를 생성하고, Swagger UI를 통해 시각적으로 제공하는 데 유용하다.

2.1. 의존성 추가

먼저, springdoc-openapi-starter-webmvc-ui를 의존성으로 추가해야 한다.

pom.xml 파일에 다음과 같은 의존성을 추가

<dependencies>
		...
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.2.0</version>
    </dependency>
</dependencies>

build.gradle을 사용하는 경우, 다음과 같이 설정

dependencies {
	...
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

2.2. 기본 설정

Spring Boot 3.x.x에서는 별도의 Swagger 설정이 필요 없다. 기본적으로 springdoc-openapi는 /v3/api-docs 경로에서 OpenAPI 문서를 제공하고, /swagger-ui.html 경로에서 Swagger UI를 제공한다.

2.3. Customization

기본 설정 외에 추가적인 설정이 필요한 경우, application.yml 또는 application.properties 파일을 사용하여 Swagger UI의 설정을 커스터마이즈할 수 있다. 예를 들어, application.yml에서 다음과 같은 설정을 할 수 있다.

3. Swagger UI 사용하기

애플리케이션을 실행한 후, 브라우저에서 http://localhost:8080/swagger-ui.html로 접속하면 Swagger UI를 통해 API 문서를 확인할 수 있다. Swagger UI는 API 엔드포인트, 요청 및 응답 예시를 제공하며, 직접 요청을 시도해볼 수도 있다.

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

4. API 문서화 추가하기

Swagger는 Javadoc 스타일의 어노테이션을 사용하여 API 문서를 더욱 상세하게 작성할 수 있다. 예를 들어, 다음과 같은 방식으로 API 엔드포인트를 설명할 수 있다:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ApiController {

    @GetMapping("/greet")
    @Operation(
        summary = "Greet User",
        description = "Returns a greeting message with the user's name",
        responses = {
            @ApiResponse(responseCode = "200", description = "Successful operation")
        }
    )
    public String greet(
        @Parameter(description = "Name of the user to be greeted") @RequestParam String name) {
        return "Hello, " + name;
    }
}

위의 예시에서는 @Operation과 @ApiResponse 어노테이션을 사용하여 API 엔드포인트에 대한 정보를 추가하고 있다.

이로 인해 Swagger UI에서 API 문서가 더욱 풍부하게 표시된다.

5. 프로젝트 적용 예시