Spring Boot 애플리케이션에 Swagger를 통한 API 문서화 적용하기

Spring Boot에서 Swagger의 중요성과 기본 설정

Swagger UI with Spring Boot

 

Swagger는 RESTful API를 설계, 구축, 문서화, 사용 및 테스트하는 데 도움을 주는 오픈 소스 프로젝트입니다. Spring Boot 애플리케이션에 Swagger를 통한 API 문서화를 적용하면, 개발자와 최종 사용자가 API를 보다 쉽게 이해하고 사용할 수 있게 됩니다. Swagger의 적용은 springfox-swagger2와 springfox-swagger-ui 라이브러리를 프로젝트의 의존성에 추가하는 것부터 시작합니다.

// build.gradle 파일의 의존성 추가 예시
dependencies {
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

이 코드는 Spring Boot 프로젝트에 Swagger를 위한 필수 의존성을 추가하는 방법을 보여줍니다.

 

Swagger 설정과 커스터마이징

Swagger 설정을 통해 API 문서화 프로세스를 커스터마이징 할 수 있습니다. SwaggerConfig 클래스를 생성하여 Swagger의 Docket Bean을 정의함으로써, API 문서의 제목, 설명, 버전 등을 설정할 수 있습니다.

// Swagger 설정 클래스 예시
@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build()
          .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfo(
          "My REST API", 
          "Some custom description of API.", 
          "API TOS", 
          "Terms of service", 
          new Contact("Jinwoong Kim", "www.w55ng.com", "jinwoong@w55ng.com"), 
          "License of API", "API license URL", Collections.emptyList());
    }
}

이 설정은 Swagger UI에서 보여질 API 문서의 기본 정보를 설정합니다.

 

API 모델과 연산 주석으로 세밀한 문서화

Spring Boot 애플리케이션에서 Swagger를 사용하면, @ApiModel과 @ApiModelProperty 주석을 통해 모델 데이터를 세밀하게 문서화할 수 있습니다. 또한, @ApiOperation과 @ApiParam 주석을 메소드와 파라미터에 추가하여, 각 API 연산의 목적과 파라미터의 세부 사항을 설명할 수 있습니다.

// API 모델 및 연산 주석 예시
@ApiModel(description="Class representing a person tracked by the application.")
public class Person {

    @ApiModelProperty(notes="Unique identifier of the Person. No two persons can have the same id.", example="1", required=true, position=0)
    private Long id;
    
    @ApiModelProperty(notes="Name of the Person", example="Jinwoong Kim", required=true, position=1)
    private String name;
    
    // Getters and Setters
}

@RestController
public class PersonController {

    @ApiOperation(value="Find person by ID", notes="Provide an ID to look up a specific person from the people data.", response=Person.class)
    @GetMapping("/people/{id}")
    public Person findPersonById(@ApiParam(value="ID value for the person you need to retrieve", required=true) @PathVariable Long id) {
        // Method implementation
    }
}

이 코드는 모델과 API 연산을 문서화하여, Swagger UI에서 사용자가 해당 API의 사용 방법을 명확히 이해할 수 있도록 합니다.

Swagger UI를 통한 API 상호작용

Swagger를 통한 API 문서화의 마지막 단계는 Swagger UI를 사용하여 실제 API와 상호작용하는 것입니다. Spring Boot 애플리케이션에 Swagger를 적용하면, 기본적으로 /swagger-ui/ 경로에서 API 문서를 볼 수 있습니다. Swagger UI는 개발자가 API를 시각적으로 탐색하고, 실제 API 요청을 보내고 응답을 받아볼 수 있게 해주는 강력한 도구입니다.

 

Swagger UI를 통해 개발자는 API의 각 엔드포인트를 테스트하고, 요청의 형식과 응답 데이터를 실시간으로 확인할 수 있습니다. 이는 API의 디버깅과 테스트 과정을 대폭 단순화하며, API의 사용법을 빠르게 익히는 데 도움을 줍니다.

 

Spring Boot 애플리케이션에 Swagger를 적용함으로써, API 문서화 과정을 자동화하고, 개발자와 최종 사용자가 API를 보다 쉽게 이해하고 사용할 수 있도록 할 수 있습니다. 이는 API의 개발과 유지보수를 효율적으로 만들며, 애플리케이션의 품질을 높일 수 있습니다.