Swagger로 API 자동 관리하기

 

API 문서를 자동으로? Swagger로 간편하게 API 관리하기

프로젝트를 진행하다 보면 프론트엔드와 백엔드 개발자 간의 소통을 위해 API 문서는 필수입니다. 하지만 API를 추가하거나 수정할 때마다 문서를 수동으로 업데이트하는 것은 번거롭고 실수가 발생하기 쉽죠. 

이런 문제를 해결하기 위해 등장한 것이 바로 Swagger입니다. Swagger는 코드와 항상 일치하는 '자동화된' API 문서를 자동으로 만들어주는 강력한 도구입니다.

---

Swagger 란? 

Swagger는 OpenAPI Specification(OAS) 라는 표준 명세를 기반으로 API를 쉽게 설계, 빌드, 문서화하고 사용할 수 있도록 도와주는 프레임워크입니다. 개발자가 API를 만들면, Swagger가 코드를 분석해서 API의 명세서를 자동으로 생성하고 이를 보기 좋은 UI로 시각화해줍니다.

마치 API의 사용설명서를 자동으로 만들어주는 것과 같아요.

주요 특징

• API 문서 자동화: 컨트롤러에 작성된 코드(@RestController, @GetMapping 등)를 기반으로 API 문서를 자동으로 생성하여 수동으로 문서를 관리할 필요가 없어집니다.
• 직관적인 UI 제공: Swagger UI를 통해 API 목록, 각 API의 요청/응답 형식, 파라미터 등을 웹 페이지에서 한눈에 볼 수 있습니다.
• API 직접 테스트: UI 화면에서 각 API의 파라미터를 입력하고 'Try it out' 버튼을 눌러 직접 API를 호출하고 응답을 확인할 수 있습니다. Postman과 같은 도구 없이도 간단한 테스트가 가능하죠.

---

Spring Boot에 Swagger 적용하기

가장 널리 사용되는 springdoc-openapi 라이브러리를 기준으로 설명하겠습니다.

1. 의존성 추가

먼저 build.gradle 또는 pom.xml에 Swagger 라이브러리 의존성을 추가합니다.

build.gradle (Gradle)

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

 

2. 실행 및 접속

놀랍게도 거의 끝입니다. 의존성만 추가하고 애플리케이션을 실행하면 Swagger 설정이 자동으로 활성화됩니다.

이후 아래 URL로 접속하면 Swagger UI 화면을 바로 확인할 수 있습니다. http://localhost:8080/swagger-ui.html

3. API 정보 커스터마이징 (선택)

기본 문서에 API 제목, 설명, 버전 등 추가 정보를 넣고 싶다면 @Configuration 클래스를 만들어 OpenAPI Bean을 등록하면 됩니다.

 

SwaggerConfig.java

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") // API 제목
                .description("프로젝트에 사용되는 API 명세서입니다.") // API 설명
                .version("1.0.0"); // API 버전
    }
}

Swagger 어노테이션으로 문서 API에 대한 설명 추가

자동으로 생성된 문서도 훌륭하지만 각 API에 대한 설명을 추가하면 훨씬 이해하기 쉬운 문서를 만들 수 있습니다.

• @Tag: API 그룹을 설정합니다. (예: "회원 API", "게시글 API")
• @Operation: 특정 API의 기능과 설명을 추가합니다. (예: "회원 가입", "게시글 상세 조회")
• @Parameter: 각 파라미터에 대한 설명을 추가합니다.
• @ApiResponse: API 응답에 대한 설명을 추가합니다. (예: 200 OK, 404 Not Found)

사용예시 Controller

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "회원 API", description = "사용자 관련 API 명세")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "회원 정보 조회", description = "사용자 ID를 통해 특정 회원의 정보를 조회합니다.")
    @GetMapping("/{userId}")
    public UserDto getUserById(
            @Parameter(name = "userId", description = "조회할 사용자의 ID") @PathVariable String userId) {
        // ... 로직 생략 ...
        return new UserDto(userId, "홍길동");
    }
}