Spring Boot RESTful API 문서화를 위한 Swagger 설정 및 활용

Swagger는 RESTful API를 설계, 구축, 문서화 및 사용하는 데 도움이 되는 강력한 오픈 소스 프레임워크이며, 다양한 도구 생태계를 지원합니다.

Spring Boot 프로젝트에 Swagger 통합하기

Swagger를 Spring Boot 프로젝트에 통합하는 방법은 다음과 같습니다.

프로젝트 구조 예시

일반적인 Spring Boot 프로젝트의 파일 구조는 다음과 같을 수 있습니다:

.
|____main
| |____java
| | |____com
| | | |____example
| | | | |____ApiApplication.java
| | | | |____controller
| | | | | |____SampleController.java
| | | | |____config
| | | | | |____SwaggerConfig.java
| |____resources
| | |____application.properties
| | |____log4j2.xml

Maven 의존성 설정

pom.xml 파일에 Spring Boot 및 Swagger 관련 의존성을 추가합니다.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>swagger-api-demo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>1.8</java.version>
        <spring.boot.version>2.7.0</spring.boot.version>
        <springfox.version>2.9.2</springfox.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Starter Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>${spring.boot.version}</version>
        </dependency>

        <!-- Swagger UI Dependencies -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>

        <!-- Lombok (Optional for boilerplate code reduction) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
            <version>1.18.24</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring.boot.version}</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Swagger 설정 클래스

Swagger 설정을 위한 Java 클래스를 생성합니다.

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger 설정 클래스
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * API 문서 설정을 위한 Docket 빈을 생성합니다.
     * @return Docket 설정 객체
     */
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // API 기본 정보 설정
                .select()
                // API 문서로 포함할 기본 패키지 경로 지정
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any()) // 모든 경로의 API 포함
                .build();
    }

    /**
     * API 문서의 기본 정보를 설정합니다.
     * @return ApiInfo 객체
     */
    private springfox.documentation.service.ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo API 서비스") // API 제목
                .description("Spring Boot 기반 데모 API 서비스 문서") // API 설명
                .version("1.0.0") // API 버전
                .contact(new Contact("Developer Team", "https://example.com", "dev@example.com")) // 연락처 정보
                .license("Apache 2.0") // 라이선스 정보
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") // 라이선스 URL
                .build();
    }
}

RequestHandlerSelectors.basePackage("com.example.controller")는 Swagger가 API 문서를 생성할 컨트롤러 클래스를 스캔할 패키지를 지정합니다.

API 컨트롤러 및 DTO 정의

API 컨트롤러와 요청/응답 DTO(Data Transfer Object)를 정의합니다. Swagger 어노테이션을 사용하여 API 설명, 파라미터 정보 등을 추가할 수 있습니다.

예제 컨트롤러 (SampleController.java)

package com.example.controller;

import com.example.dto.SampleRequestDto;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 샘플 API 컨트롤러
 */
@RestController
@RequestMapping("/api/sample")
@Api(value = "Sample API", tags = "샘플 API 컨트롤")
public class SampleController {

    @ApiOperation(value = "간단한 인사말 반환", notes = "이 API는 간단한 환영 메시지를 반환합니다.")
    @GetMapping("/greet")
    public String greetUser(
            @ApiParam(value = "사용자 이름", required = false, defaultValue = "Guest")
            @RequestParam(required = false, defaultValue = "Guest") String userName) {
        return "Hello, " + userName + "!";
    }

    @ApiOperation(value = "샘플 데이터 생성", notes = "요청 DTO를 받아 샘플 데이터를 생성하고 결과를 반환합니다.")
    @PostMapping("/create")
    public String createSample(
            @ApiParam(value = "샘플 생성 요청 데이터", required = true)
            @RequestBody SampleRequestDto requestDto) {
        // 실제 데이터 생성 로직 구현
        System.out.println("Received data: " + requestDto);
        return "Sample created successfully for " + requestDto.getName();
    }
}

예제 DTO (SampleRequestDto.java)

package com.example.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**
 * 샘플 요청 DTO
 */
@ApiModel(description = "샘플 데이터 생성 요청 객체")
public class SampleRequestDto implements Serializable {

    @ApiModelProperty(value = "샘플 이름", required = true, example = "MySample")
    private String name;

    @ApiModelProperty(value = "샘플 설명", required = false, example = "This is a sample description.")
    private String description;

    @ApiModelProperty(value = "수량", required = true, example = "1")
    private Integer quantity;

    // Getter, Setter, toString() 메소드 (Lombok 사용 시 자동 생성)

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public Integer getQuantity() {
        return quantity;
    }

    public void setQuantity(Integer quantity) {
        this.quantity = quantity;
    }

    @Override
    public String toString() {
        return "SampleRequestDto{" +
               "name='" + name + '\'' +
               ", description='" + description + '\'' +
               ", quantity=" + quantity +
               '}';
    }
}

애플리케이션 실행 및 API 문서 접속

Spring Boot 애플리케이션을 실행한 후, 웹 브라우저를 통해 Swagger UI에 접속할 수 있습니다.

기본적으로 Swagger UI는 /swagger-ui.html 경로에서 제공됩니다. 예를 들어, 애플리케이션 포트가 8080이라면 다음 URL로 접속합니다:

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

Swagger UI 기능

Swagger UI를 통해 다음과 같은 작업을 수행할 수 있습니다:

  • API 탐색: 정의된 모든 API 엔드포인트를 확인하고 탐색할 수 있습니다.
  • API 상세 정보: 각 API의 HTTP 메소드, 경로, 요청 파라미터, 응답 형식 등을 확인할 수 있습니다.
  • API 테스트: "Try it out" 기능을 사용하여 실제 API를 호출하고 응답을 확인할 수 있습니다. 요청 파라미터를 직접 입력하거나 수정하며 테스트할 수 있습니다.

주요 Swagger 어노테이션 설명

  • @Api: 클래스 레벨에서 API 그룹을 정의합니다. tags 속성을 사용하여 UI에 표시될 그룹 이름을 지정할 수 있습니다.
  • @ApiOperation: 메소드 레벨에서 API 작업에 대한 설명을 제공합니다. value는 작업의 요약, notes는 추가 상세 설명을 나타냅니다.
  • @ApiParam: 메소드 파라미터에 대한 메타데이터를 정의합니다. value (설명), required (필수 여부), defaultValue (기본값), example (예시 값) 등을 설정할 수 있습니다.
  • @ApiImplicitParam / @ApiImplicitParams: 특정 파라미터에 대한 상세 정보를 명시적으로 지정할 때 사용됩니다. (@ApiParam보다 더 세밀한 제어가 가능합니다.)
  • @ApiModel: DTO 클래스 레벨에서 API 응답/요청 모델에 대한 설명을 정의합니다.
  • @ApiModelProperty: DTO 클래스의 필드에 대한 설명을 정의합니다. value (설명), required (필수 여부), example (예시 값) 등을 설정할 수 있습니다.

주의: @ApiParam이나 @ApiImplicitParam에서 required = true로 설정하더라도, 이는 Swagger UI 내에서의 동작이며 실제 Spring MVC의 파라미터 필수 검증을 대체하지는 않습니다. 필요한 경우 @RequestParam(required = true) 또는 @RequestBody와 같은 Spring 기본 어노테이션을 함께 사용해야 합니다.

고려 사항

Swagger UI는 API 문서화 및 테스트에 매우 유용하지만, 많은 어노테이션 사용으로 인해 코드 가독성이 다소 떨어질 수 있습니다. API 설계 시에는 이러한 점을 고려하여 적절한 수준의 어노테이션을 사용하는 것이 좋습니다. 일부 프로젝트에서는 API 문서화를 위한 별도의 도구(예: yAPI)와 함께 사용하기도 합니다.

태그: Spring Boot swagger RESTful API API 문서화 java

10월 26일 02:43에 게시됨