Swagger를 활용한 REST API 문서 자동화

개요 Swagger는 RESTful 웹 서비스의 설계, 생성, 호출 및 시각화를 지원하는 표준 프레임워크입니다. 이 도구를 통해 서버 코드와 문서가 동기화되며, 클라이언트 측에서도 최신 상태의 API 정보를 실시간으로 접근할 수 있습니다. 특히 개발 중에는 빠른 테스트와 문서 확인이 가능하고, 생산 환경에서는 비활성화하여 보안을 강화할 수 있습니다.
Spring Boot와 Swagger 연동

2.1 Spring Boot 프로젝트 생성 기본적인 Spring Boot 프로젝트를 생성합니다.

2.2 의존성 추가 Maven에 다음 종속성을 포함시킵니다:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.3 간단한 컨트롤러 작성 SwaggerController.java 파일을 생성하여 기본 응답을 반환하는 엔드포인트를 구현합니다:

package com.dz.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerController {

    @GetMapping("/hello")
    public String greet() {
        return "Hello from Swagger!";
    }
}

2.4 Swagger 설정 구성 config 패키지에 SwaggerConfig.java 클래스를 생성하고, Swagger 활성화를 위한 설정을 추가합니다:

package com.dz.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket apiDocket(Environment env) {
        // 프로파일 기반으로 활성화 여부 결정
        Profiles profiles = Profiles.of("dev", "test");
        boolean isDevOrTest = env.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isDevOrTest)
                .groupName("api-v1")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dz.controller"))
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact(
            "개발자 이름",
            "https://blog.example.com",
            "developer@example.com"
        );

        return new ApiInfoBuilder()
                .title("API 문서 - v1")
                .description("RESTful API에 대한 자동 문서화")
                .version("1.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }
}

2.5 테스트 애플리케이션을 실행한 후, 브라우저에서 아래 주소로 접속:

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

고급 설정 옵션

3.1 API 정보 커스터마이징 ApiInfo 객체를 통해 제목, 설명, 버전, 라이선스 등 정보를 정의할 수 있습니다.

3.2 스캔 범위 조정 RequestHandlerSelectors와 PathSelectors를 사용해 특정 패키지나 경로만 스캔하도록 제한합니다:

.select()
.apis(RequestHandlerSelectors.basePackage("com.dz.controller"))
.paths(PathSelectors.ant("/api/v1/**"))

3.3 환경별 활성화 개발 및 테스트 환경에서만 Swagger를 활성화하고, 운영 환경에서는 비활성화합니다:

boolean isActive = environment.acceptsProfiles(Profiles.of("dev", "test"));
return new Docket(DocumentationType.SWAGGER_2).enable(isActive);

3.4 다중 그룹 설정 여러 그룹으로 나누어 다양한 서비스를 관리할 수 있습니다:

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("user-service")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.dz.controller.user"))
            .build();
}

@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("order-service")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.dz.controller.order"))
            .build();
}

3.5 API 문서 주석 적용

3.5.1 모델 클래스에 주석 추가 엔티티 클래스에 @ApiModel과 @ApiModelProperty를 사용하여 설명을 부여합니다:

package com.dz.model;

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

@ApiModel(description = "사용자 정보 데이터베이스 엔티티")
public class UserDTO {

    @ApiModelProperty(value = "고유 식별자", example = "12345")
    private Long id;

    @ApiModelProperty(value = "사용자 이름 (필수)", required = true)
    private String name;

    @ApiModelProperty(value = "비밀번호 (암호화 처리됨)")
    private String password;

    // getter/setter 생략
}

3.5.2 컨트롤러 메서드 주석 메서드 수준에서 @ApiOperation과 @ApiParam으로 설명을 제공합니다:

@PostMapping("/create")
@ApiOperation(value = "사용자 생성 요청", notes = "입력된 정보로 새로운 사용자를 생성합니다.")
public ResponseEntity<UserDTO> createUser(
        @ApiParam(value = "생성할 사용자 정보", required = true)
        @RequestBody UserDTO userData) {

    // 로직 처리
    return ResponseEntity.ok(userData);
}

결론

Swagger를 통해 복잡한 파라미터나 응답 구조를 명확하게 문서화할 수 있습니다.
실시간으로 변경되는 API를 자동으로 반영하여 유지보수가 용이합니다.
실제 요청을 시뮬레이션하며 테스트 가능.
운영 환경에서는 반드시 Swagger를 비활성화해야 하며, 보안 및 리소스 절약을 위해 필수입니다.

태그: Spring Boot swagger REST API API 문서화 openapi

7월 26일 00:03에 게시됨

괴물 클럽

Swagger를 활용한 REST API 문서 자동화

인기 태그