Swagger로 API 문서화하기

기본 환경

Java 17
SpringBoot 3.2.3
IntelliJ
Mac OS (M3)

1. Swagger란?

Swagger는 API를 설명하고 문서화하며, 개발 및 테스트를 용이하게 하는 오픈 소스 프레임워크입니다. Swagger는 RESTful API를 문서화하고 사용할 수 있는 툴이며, API의 명세를 정의하고 해당 명세를 기반으로 자동으로 API 문서를 생성할 수 있습니다.

더 자세한 내용은 다음 링크를 방문해 확인하기 바랍니다.
swagger 공식문서

2. Swagger을 쓰는 이유

• 문서화의 편의성
  Swagger를 사용하면 API의 명세를 정의하고 이를 토대로 자동으로 문서를 생성할 수 있어 개발자들에게 큰 편의성을 제공합니다.
  
• 간편한 테스트
  Swagger UI를 통해 API의 동작을 시뮬레이션하고 테스트할 수 있습니다. 이는 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 도와줍니다.
  
• 표준화된 API
  Swagger를 이용하면 API의 명세를 통일된 형식으로 작성할 수 있어, 팀 간의 협업이 용이해집니다.

3. 연동하는 방법

1) 의존성 목록에 라이브러리 추가

// swagger 적용
	implementation "org.springdoc:springdoc-openapi-starter-common:${springDocVersion}"
	implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:${springDocVersion}"

2) yml에 추가

  swagger-ui:
    path: /
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha
    doc-expansion: none

3) SwaggerConfig 클래스 추가

import io.swagger.v3.oas.models.Components;
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
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("API service")
                .description("API를 제공하는 서비스입니다.")
                .version("1.0.0");
    }
}

4) API 등록하기 : Controller에 어노테이션 추가하기

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
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.RestController;

@RestController
@RequestMapping("v1/route")
@RequiredArgsConstructor
@Tag(name = "길찾기 관련 API", description = "안전길찾기에 대한 라우팅 시스템의 API를 제공합니다.")
public class RouteController {
    private final RouteService routeService;
    @PostMapping
    @Operation(summary = "안전 길찾기", description = "사용자가 입력한 출발지와 도착지에 맞는 안전 길찾기를 합니다.")
    public RouteCreateResponse createResponse(
            @RequestBody RouteCreateRequest request
            ){
        return routeService.createRoute(request);
    }
}

4. 확인

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

스프링부트 실행 후, 해당 주소로 방문하여 등록된 API를 확인합니다.

이러면 성공 !