[Spring] Swagger UI와 OpenAPI 문서화 정리

API 명세를 자동으로 만들고 직접 테스트하는 방법

REST API를 개발하면 프론트엔드 개발자나 다른 백엔드 개발자에게 다음 정보를 전달해야 한다.

어떤 URL을 호출해야 하는가?
어떤 HTTP Method를 사용하는가?
요청 데이터는 어떤 형식인가?
성공과 실패 시 무엇을 반환하는가?

이 내용을 별도의 문서에 수작업으로 작성하면 실제 코드가 변경되었는데 문서는 갱신되지 않는 문제가 생길 수 있다.

Spring Boot에서는 springdoc-openapi를 사용해 Controller와 DTO를 분석하고, OpenAPI 명세와 Swagger UI를 자동으로 생성할 수 있다.

---

1. OpenAPI와 Swagger UI의 차이

두 용어는 함께 등장하지만 역할이 다르다.

OpenAPI Specification
→ REST API를 표현하는 표준 명세

Swagger UI
→ OpenAPI 명세를 웹 화면으로 보여 주는 도구

OpenAPI 문서에는 다음과 같은 내용이 포함된다.

• API 경로와 HTTP Method
• Path Variable과 Query Parameter
• Request Body 구조
• Response Body 구조
• HTTP 상태 코드
• DTO의 필드와 데이터 타입

Swagger UI는 이러한 명세를 사람이 보기 쉬운 화면으로 표현하며, 브라우저에서 API를 직접 호출해 볼 수 있는 기능도 제공한다.

Spring Controller와 DTO
→ springdoc-openapi가 분석
→ OpenAPI JSON 생성
→ Swagger UI에서 시각화

---

2. Spring Boot에 Swagger UI 적용하기

Gradle 프로젝트에서는 다음 의존성을 추가한다.

dependencies {
    implementation(
        "org.springdoc:" +
        "springdoc-openapi-starter-webmvc-ui"
    )
}

Maven 프로젝트에서는 다음과 같이 설정한다.

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

프로젝트와 Spring Boot 버전에 맞는 springdoc-openapi 버전을 지정한 뒤 애플리케이션을 실행하면 별도의 복잡한 설정 없이 기본 문서가 생성된다.

일반적인 확인 경로는 다음과 같다.

Swagger UI
http://localhost:8080/swagger-ui/index.html

OpenAPI JSON
http://localhost:8080/v3/api-docs

/v3/api-docs는 기계가 읽을 수 있는 JSON 명세이고, Swagger UI는 해당 명세를 브라우저 화면으로 표현한다.

---

3. 주요 OpenAPI 어노테이션

Controller와 DTO에 어노테이션을 추가하면 문서의 설명을 더 구체적으로 작성할 수 있다.

어노테이션역할

어노테이션	역할
@Tag	Controller 단위의 API 그룹 설명
@Operation	개별 API의 기능 설명
@Parameter	Path·Query Parameter 설명
@ApiResponse	상태 코드별 응답 설명
@Schema	DTO와 필드 설명
@Hidden	문서에서 특정 API 제외

간단한 상품 조회 API

@Tag(
    name = "상품 API",
    description = "상품 조회와 관리 기능"
)
@RestController
@RequestMapping("/api/products")
@RequiredArgsConstructor
public class ProductController {

    private final ProductService productService;

    @Operation(
        summary = "상품 상세 조회",
        description = "상품 ID를 이용해 상품 정보를 조회합니다."
    )
    @ApiResponse(
        responseCode = "200",
        description = "상품 조회 성공"
    )
    @ApiResponse(
        responseCode = "404",
        description = "상품을 찾을 수 없음"
    )
    @GetMapping("/{id}")
    public ProductResponse findById(
            @Parameter(
                description = "조회할 상품 ID",
                example = "1"
            )
            @PathVariable Long id
    ) {
        return productService.findById(id);
    }
}

Swagger UI에는 상품 API라는 그룹이 생성되고, 해당 API의 설명과 파라미터, 예상 응답 코드가 표시된다.

---

응답 DTO 설명하기

@Schema(description = "상품 조회 응답")
public record ProductResponse(

        @Schema(
            description = "상품 ID",
            example = "1"
        )
        Long id,

        @Schema(
            description = "상품명",
            example = "무선 마우스"
        )
        String name,

        @Schema(
            description = "상품 가격",
            example = "15000"
        )
        int price
) {
}

@Schema를 사용하면 각 필드의 의미와 예시가 Swagger UI의 Schema 영역에 표시된다.

이를 통해 API 사용자는 실제 코드를 열어 보지 않아도 응답 구조를 파악할 수 있다.

자료에서도 Controller에는 @Tag와 @Operation, 파라미터에는 @Parameter, DTO에는 @Schema를 사용해 문서의 부가정보를 작성하는 예제를 보여 준다.

---

4. Swagger UI를 사용할 때 주의할 점

Swagger UI가 자동으로 API를 찾아 주더라도 좋은 문서가 자동으로 완성되는 것은 아니다.

다음 내용을 명확하게 작성해야 한다.

API가 무엇을 수행하는가?
어떤 값이 필수인가?
정상 응답은 어떤 형태인가?
어떤 오류가 발생할 수 있는가?

또한 OpenAPI의 @RequestBody와 Spring MVC의 @RequestBody는 이름이 같지만 역할이 다르다.

Spring @RequestBody
→ 요청 JSON을 Java 객체로 변환

OpenAPI @RequestBody
→ 요청 본문의 구조를 문서에 설명

두 어노테이션은 패키지도 다르므로 Import할 때 주의해야 한다.

운영 환경에서는 Swagger UI를 외부에 그대로 공개할지도 검토해야 한다. 내부 API 구조와 테스트 가능한 Endpoint가 노출될 수 있으므로, 개발 환경에서만 활성화하거나 인증된 사용자만 접근하도록 제한할 수 있다.

---

핵심 정리

OpenAPI
→ API를 표현하는 표준 명세

springdoc-openapi
→ Spring Controller와 DTO를 분석해 명세 생성

Swagger UI
→ OpenAPI 명세를 화면으로 표현하고 API 호출 지원

Swagger UI의 가장 큰 장점은 단순히 보기 좋은 API 목록을 만드는 것이 아니다.

실제 Controller와 DTO를 바탕으로 API 계약을 문서화하고, 개발자들이 동일한 명세를 확인하며 직접 테스트할 수 있게 만드는 데 의미가 있다.

코드와 문서를 함께 관리하면 프론트엔드와 백엔드의 협업이 쉬워지고, API가 변경되었을 때 발생하는 문서 불일치도 줄일 수 있다.