[Spring] Swagger 설정 및 사용 방법

📑 개요

Swagger를 사용하여 API 명세를 작성해보고자 한다.

 

📑 개발 환경

SpringBoot : 3.3.5
JDK : 17
build Tools : gradle
Editor : InteliJ

 

📑 의존성 추가

Spring Boot 3.x 버전에서의 Swagger 적용을 위한 의존성 추가

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'

 

📑 Swagger Config 작성

package withbeetravel.config;

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;

@Configuration // 설정 파일을 읽기 위한 annotation
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {

        // Swagger에서 보여줄 API 정보 설정
        Info info = new Info()
                .version("1.0.0") // 서비스 버전
                .title("WithBee Travel") // 타이틀
                .description("WithBee Travel🐝🛫 Project API"); // 설명

        return new OpenAPI().info(info);
    }
}

 

📑 Swagger 접속 확인

기본적인 swagger 접속 URL은 다음과 같다.

{서비스 기본 URL}/swagger-ui/index.html

현재 로컬에서 접속 테스트를 해볼 것이고,

우리 프로젝트에선 따로 지정해준 context-path가 없으니 다음 URL로 접속한다.

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

그럼 다음과 같이 swagger에 접속할 수 있다.

 

📑 Swagger 작성을 위한 Annotation

👉 @Tag

API 그룹을 정의하고 설명할 수 있는 메타데이터를 제공하여, API 엔드포인트를 기능별로 묶어 관리하기 쉽게 도와준다.

 

@Tag는 일반적으로 클래스 레벨에 적용된다.

각 @RestController 클래스나 특정 API 그룹을 대표하는 클래스에 추가하여 해당 그룹의 설명을 작성할 수 있다.

package withbeetravel.controller;

import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/travels/{travelId}/payments")
@Tag(name = "공동 결제 내역 API", description = "에 대한 설명입니다.")
public class PaymentController {

	...
}

• name: 태그 이름 지정
• description: 태그에 대한 설명을 추가하여 해당 API 그룹의 역할과 기능을 설명할 수 있다.

위와 같이 @Tag annotation을 붙여주면 swagger에서 다음과 같이 확인할 수 있다.

 

👉 @Operation

OpenAPI 문서에 특정 API 엔드포인트의 상세한 정보를 추가할 때 사용된다.

 

@Operation은 메서드 레벨에서 적용되며

API의 기능, 설명, 요청과 응답의 세부사항 등을 정의할 수 있다.

package withbeetravel.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import withbeetravel.dto.ChooseParticipantsRequestDto;
import withbeetravel.dto.SuccessResponseDto;

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/travels/{travelId}/payments")
@Tag(name = "공동 결제 내역 API", description = "에 대한 설명입니다.")
public class PaymentController {

    @Operation(
            summary = "정산 인원 선택",
            description = "공동 결제 내역에 대한 정산 인원을 선택할 수 있습니다.",
            tags = {"User Management"}
    )
    @PatchMapping("/{sharedPaymentId}/participants")
    public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                                @PathVariable Long sharedPaymentId,
                                                                @RequestBody ChooseParticipantsRequestDto requestDto) {

        return null;
    }
}

• summary:
  API 엔드포인트의 간략한 설명을 제공한다.
  Swagger UI에서 API 제목으로 표시되며, 엔드포인트의 주요 기능을 한눈에 파악할 수 있다.
• description:
  API 엔드포인트에 대한 상세 설명을 추가할 수 있다.
  이 필드는 API의 동작 방식이나 추가적인 세부사항을 전달하는 데 유용하다.
• tags:
  API를 특정 태그와 연결할 수 있다.
  태그를 통해 엔드포인트를 기능별로 그룹화하여 Swagger UI에서 관리할 수 있다.
• parameters:
  API가 사용하는 파라미터에 대한 정보를 제공할 수 있다.
  URL 경로에 있는 @PathVariable이나 @RequestParam 등에 대해 설명을 추가하고 싶은 경우 사용한다.
  (아래에 더 자세히 다루겠다.)

위와 같이 @Operation annotation을 붙여주면 swagger에서 다음과 같이 확인할 수 있다.

 

User Management 태그를 등록한 API도 따로 모아볼 수 있다.

 

👉 @Parameter

@Operation이나 @RequestMapping, @GetMapping, @PostMapping 등의 메서드 레벨 annotation과 함께 사용하여

API의 요청 파라미터(쿼리 파라미터, 경로 파라미터, 헤더, 요청 본문 등)를 설명한다.

package withbeetravel.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import withbeetravel.dto.ChooseParticipantsRequestDto;
import withbeetravel.dto.SuccessResponseDto;

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/travels/{travelId}/payments")
@Tag(name = "공동 결제 내역 API", description = "에 대한 설명입니다.")
public class PaymentController {

    @Operation(
            summary = "정산 인원 선택",
            description = "공동 결제 내역에 대한 정산 인원을 선택할 수 있습니다.",
            tags = {"User Management"},
            parameters = {
                    @Parameter(
                            name = "travelId",
                            description = "여행 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    ),
                    @Parameter(
                            name = "sharedPaymentId",
                            description = "공동 결제 내역 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    )
            }
    )
    @PatchMapping("/{sharedPaymentId}/participants")
    public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                                @PathVariable Long sharedPaymentId,
                                                                @RequestBody ChooseParticipantsRequestDto requestDto) {

        return null;
    }
}

• name (필수):
  파라미터의 이름을 지정한다.
  이 이름은 API 요청 시 사용되는 파라미터 이름과 일치해야 한다.
• description:
  파라미터의 역할이나 용도를 설명하는 텍스트다.
  Swagger UI에서 이 설명이 API 문서에 표시된다.
• required:
  필수인지 여부를 설정한다.
  true로 설정하면 이 파라미터는 필수로 요구된다.
  기본값은 false이다.
• in:
  파라미터가 위치하는 곳을 지정한다.
  경로 파라미터는 path, 쿼리 파라미터는 query, 요청 헤더는 header, 요청 본문은 default로 설정할 수 있다.
  기본값은 query이다.
• example:
  해당 파라미터의 예시 값을 제공한다.
  Swagger UI에서 API 테스트 시 예시 값을 확인할 수 있다.
• allowEmptyValue:
  파라미터가 빈 값(ex. 빈 문자열, null)도 허용하는지 여부를 설정한다.
  true로 설정하면 빈 값도 허용된다.
  기본값은 false이다.

위와 같이 @Parameter annotation을 붙여주면 swagger에서 다음과 같이 확인할 수 있다.

 

👉 @Schema

모델 클래스와 그 필드에 대한 설명을 추가할 수 있다.

주로 DTO, 모델 클래스, 그리고 해당 클래스의 필드에 적용하여 API 문서에서 해당 객체의 스키마를 정의한다.

package withbeetravel.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;

import java.util.List;

@Getter
@Schema(description = "공동 결제 내역에 대한 정산 인원 리스트 DTO")
public class ChooseParticipantsRequestDto {

    @Schema(
            description = "정산 인원 리스트",
            example = "[17, 19, 22, 27]"
    )
    List<Long> travelMembersId;
}

• description:
  필드나 클래스에 대한 설명을 제공한다.
  해당 필드나 클래스의 의미를 설명하는 데 사용된다.
• defaultValue:
  필드에 대한 기본값을 지정한다.
  해당 필드의 기본값으로 표시된다.
• example:
  필드의 예시 값을 제공한다.
  예시 데이터를 보여주기 위해 사용된다.
• allowableValues:
  필드의 값이 특정 값들 중 하나로 제한될 경우 사용된다.
  enum 타입 필드에 적용할 수 있다.

위와 같이 @Schema annotation을 붙여주면 swagger에서 다음과 같이 확인할 수 있다.

 

👉 @ApiResponse

API 요청이 성공하거나 실패할 때 클라이언트가 받을 수 있는 응답 코드와 설명을 제공하여
API 사용자가 어떤 종류의 응답을 예상할 수 있는지 알 수 있도록 한다.

package withbeetravel.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import withbeetravel.dto.ChooseParticipantsRequestDto;
import withbeetravel.exception.dto.ErrorResponseDto;

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/travels/{travelId}/payments")
@Tag(name = "공동 결제 내역 API", description = "에 대한 설명입니다.")
public class PaymentController {

    @Operation(
            summary = "정산 인원 선택",
            description = "공동 결제 내역에 대한 정산 인원을 선택할 수 있습니다.",
            tags = {"User Management"},
            parameters = {
                    @Parameter(
                            name = "travelId",
                            description = "여행 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    ),
                    @Parameter(
                            name = "sharedPaymentId",
                            description = "공동 결제 내역 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    )
            }
    )
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "정산인원 변경 성공"),
            @ApiResponse(responseCode = "401", description = "AUTH-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "404", description = "TRAVEL-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "403", description = "TRAVEL-002", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "404", description = "PAYMENT-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
    })
    @PatchMapping("/{sharedPaymentId}/participants")
    public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                                @PathVariable Long sharedPaymentId,
                                                                @RequestBody ChooseParticipantsRequestDto requestDto) {


        return ResponseEntity.ok("정산인원 변경 성공");
    }
}

• responseCode:
  HTTP 응답 코드를 나타내며 "200", "400", "404", "500" 등과 같은 상태 코드를 입력한다.
• description:
  해당 응답 코드에 대한 설명을 입력하여 클라이언트가 해당 상태 코드의 의미를 이해할 수 있도록 한다.
• content:
  @Content와 함께 사용되어 응답의 내용 유형과 스키마를 정의한다.
  @Schema를 통해 반환되는 데이터의 구조를 설명할 수 있다.

 

이와 같이 @ApiResponse annotation을 붙여주면 swagger에서 다음과 같이 확인할 수 있다.

 

📑 Swagger 작성 최적화

현재 코드를 보면, chooseParticipant 메서드 안에 구현부는 하나도 없음에도 swagger 설정만으로도 코드가 너무 길다.

@Operation(
        summary = "정산 인원 선택",
        description = "공동 결제 내역에 대한 정산 인원을 선택할 수 있습니다.",
        tags = {"User Management"},
        parameters = {
                @Parameter(
                        name = "travelId",
                        description = "여행 ID",
                        required = true,
                        in = ParameterIn.PATH,
                        example = "1234"
                ),
                @Parameter(
                        name = "sharedPaymentId",
                        description = "공동 결제 내역 ID",
                        required = true,
                        in = ParameterIn.PATH,
                        example = "1234"
                )
        }
)
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "정산인원 변경 성공"),
        @ApiResponse(responseCode = "401", description = "AUTH-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
        @ApiResponse(responseCode = "404", description = "TRAVEL-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
        @ApiResponse(responseCode = "403", description = "TRAVEL-002", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
        @ApiResponse(responseCode = "404", description = "PAYMENT-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
})
@PatchMapping("/{sharedPaymentId}/participants")
public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                            @PathVariable Long sharedPaymentId,
                                                            @RequestBody ChooseParticipantsRequestDto requestDto) {


    return ResponseEntity.ok("정산인원 변경 성공");
}

인터페이스를 활용하여 swagger 설정을 하고 가독성을 높여보도록 하겠다.

 

swagger docs용 interface를 생성하여 swagger 관련 설정들은 모두 이 곳에 적어준다.

package withbeetravel.controller.docs;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import withbeetravel.dto.ChooseParticipantsRequestDto;
import withbeetravel.exception.dto.ErrorResponseDto;

@Tag(name = "공동 결제 내역 API", description = "에 대한 설명입니다.")
public interface PaymentControllerDocs {

    @Operation(
            summary = "정산 인원 선택",
            description = "공동 결제 내역에 대한 정산 인원을 선택할 수 있습니다.",
            tags = {"User Management"},
            parameters = {
                    @Parameter(
                            name = "travelId",
                            description = "여행 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    ),
                    @Parameter(
                            name = "sharedPaymentId",
                            description = "공동 결제 내역 ID",
                            required = true,
                            in = ParameterIn.PATH,
                            example = "1234"
                    )
            }
    )
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "정산인원 변경 성공"),
            @ApiResponse(responseCode = "401", description = "AUTH-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "404", description = "TRAVEL-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "403", description = "TRAVEL-002", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "404", description = "PAYMENT-001", content = @Content(schema = @Schema(implementation = ErrorResponseDto.class))),
    })
    public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                    @PathVariable Long sharedPaymentId,
                                                    @RequestBody ChooseParticipantsRequestDto requestDto);
}

그리고 이 interface를 컨트롤러에서 implements 해주면

package withbeetravel.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import withbeetravel.controller.docs.PaymentControllerDocs;
import withbeetravel.dto.ChooseParticipantsRequestDto;

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/travels/{travelId}/payments")
public class PaymentController implements PaymentControllerDocs {


    @PatchMapping("/{sharedPaymentId}/participants")
    public ResponseEntity<String> chooseParticipant(@PathVariable Long travelId,
                                                                @PathVariable Long sharedPaymentId,
                                                                @RequestBody ChooseParticipantsRequestDto requestDto) {

        return ResponseEntity.ok("정산인원 변경 성공");
    }
}

이와 같이 컨트롤러는 가독성을 높이며 swagger 설정을 할 수 있다.

 

📑 참고

https://velog.io/@fever-max/Spring-Boot3-%EC%8A%A4%EC%9B%A8%EA%B1%B0Swagger-%EC%84%A4%EC%A0%95-%EB%B0%8F-%EC%82%AC%EC%9A%A9-%EB%B0%A9%EB%B2%95

https://infinitecode.tistory.com/65