Swagger를 활용한 API 문서화

Swagger는 REST API를 설계, 문서화, 테스트하기 위한 오픈소스 프레임워크입니다. 백엔드 서버가 제공하는 API를 시각적으로 확인하고, 실제 요청을 보낼 수 있는 환경을 제공합니다. 최근에는 Swagger의 명칭이 OpenAPI로 통합되어 사용되고 있습니다.

 

이번 글에서는 Swagger의 개념과 구성 요소, 그리고 Spring Boot 환경에서의 설정 및 활용 방법에 대해 자세히 알아보도록 하겠습니다.

---

1. Swagger의 필요성

API 개발 과정에서는 클라이언트 개발자나 다른 팀원이 API 명세를 정확히 알지 못해 생기는 문제가 자주 발생합니다.
예를 들어, 엔드포인트 주소, HTTP 메서드, 요청 파라미터, 응답 형식을 문서로 따로 관리할 경우 버전이 달라지거나 실제 코드와 불일치할 가능성이 높습니다.

Swagger ui 예시 이미지

Swagger는 코드 기반으로 문서를 자동 생성함으로써 이러한 문제를 해결합니다. 즉, API 명세와 코드가 항상 동기화된 상태로 유지되도록 보장합니다.

 

이를 통해 API 변경 사항이 발생하더라도 문서가 자동으로 갱신되므로, 개발자 간의 커뮤니케이션 효율이 향상됩니다.

---

2. Swagger의 구성 요소

Swagger는 크게 Swagger Editor, UI, Codegen 세 가지 핵심 구성 요소로 이루어져 있습니다.

 

1) Swagger Editor

: 브라우저에서 OpenAPI 명세 파일(YAML 또는 JSON 형식)을 작성하고 미리보기할 수 있는 도구입니다.
명세서 내에서 API의 요청, 응답, 파라미터, 모델 구조를 직접 정의할 수 있으며 Swagger UI와 연동하여 결과를 즉시 확인할 수 있습니다.

 

2) Swagger UI

: 작성된 OpenAPI 명세 파일을 기반으로 웹 페이지 형태의 인터페이스를 자동 생성하는 도구입니다. 이 UI에서는 API 명세를 시각적으로 확인할 수 있을 뿐 아니라, 직접 요청을 전송하고 응답을 확인하는 기능도 제공합니다. 개발자 입장에서는 테스트와 문서화를 동시에 수행할 수 있는 환경을 제공받게 됩니다.

 

3) Swagger Codegen

: OpenAPI 명세 파일을 기반으로 서버 또는 클라이언트의 코드를 자동 생성하는 도구입니다. 예를 들어, 명세서에서 정의한 API 엔드포인트를 기반으로 Spring Boot, Node.js, Python Flask 등 다양한 언어로 스켈레톤 코드를 자동 생성할 수 있습니다.
이 기능은 대규모 프로젝트나 멀티 플랫폼 개발 시 생산성을 크게 향상시킵니다.

---

3. Spring Boot에서 Swagger 설정하기

Spring Boot에서는 일반적으로 Swagger 3(OpenAPI 3) 버전을 사용합니다. 의존성을 추가하기 위해 build.gradle 또는 pom.xml에 다음 코드를 추가합니다.

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

 

 

별도의 설정 파일을 작성하지 않아도 기본적으로 프로젝트의 컨트롤러 메서드가 자동으로 인식되어 문서화됩니다.

 

다만, Spring Security를 사용하는 경우에는 Swagger 리소스 경로를 명시적으로 허용해야 합니다. 다음 설정을 추가합니다.

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/swagger-ui/**",
                    "/swagger-ui.html",
                    "/v3/api-docs/**",
                    "/v3/api-docs.yaml"
                ).permitAll()
                .anyRequest().authenticated()
            )
            .csrf(csrf -> csrf.disable()); // 필요 시 조정

        return http.build();
    }
}

설정 후 접근 경로는 기본적으로 다음과 같습니다. /swagger-ui/index.html, /v3/api-docs , /v3/api-docs.yaml

API에 인증이 걸려 있는 경우 Swagger UI의 Try it out 요청은 401이 발생할 수 있습니다.

이때는 Security에서 해당 엔드포인트에 대한 인증 방식(Basic, Bearer 등)을 적용하거나 Swagger의 Authorization 설정을 통해 토큰을 전달하도록 합니다.

 

이후 애플리케이션을 실행하면 기본적으로 다음 주소에서 Swagger UI를 확인할 수 있습니다.

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

스웨거 실행 화면

 

---

4. Swagger 주요 어노테이션

Swagger는 Java 코드 내의 어노테이션을 기반으로 API 명세를 자동 생성합니다.
주요 어노테이션은 다음과 같습니다.

• @Operation(summary, description) : API의 요약 및 상세 설명을 작성합니다.
• @Parameter(description) : 요청 파라미터의 역할을 설명합니다.
• @Schema(description) : DTO 클래스의 필드에 대한 설명을 작성합니다.
• @ApiResponse(responseCode, description) : HTTP 응답 코드와 설명을 지정합니다.
• @Tag(name, description) : 컨트롤러 단위로 API를 그룹화합니다.

다음은 간단한 예시입니다.

@Tag(name = "User", description = "회원 관련 API")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "회원 조회", description = "특정 ID의 회원 정보를 조회합니다.")
    @ApiResponse(responseCode = "200", description = "성공적으로 회원 정보를 반환합니다.")
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(
            @Parameter(description = "조회할 회원의 ID") @PathVariable Long id) {
        UserResponse user = userService.getUserById(id);
        return ResponseEntity.ok(user);
    }
}

위 코드와 같이 어노테이션을 작성하면, Swagger UI에서 자동으로 문서가 생성되어
API 요청 경로, 파라미터, 응답 형식이 시각적으로 표시됩니다.

---

5. Swagger UI 커스터마이징

Swagger UI는 단순한 문서 뷰어를 넘어, 프로젝트에 맞게 다양한 설정을 커스터마이징할 수 있습니다.
application.yml에 다음과 같은 설정을 추가하여 UI의 동작 방식을 제어할 수 있습니다.

springdoc:
  swagger-ui:
    path: /docs
    operationsSorter: method
    tagsSorter: alpha
    display-request-duration: true

• path : Swagger UI 접근 경로를 변경합니다. (기본값: /swagger-ui/index.html)
• operationsSorter : API를 HTTP 메서드(GET, POST 등) 순으로 정렬합니다.
• tagsSorter : API 그룹을 알파벳 순으로 정렬합니다.
• display-request-duration : 요청 처리 시간을 표시합니다.

이 설정을 통해 팀의 문서 관리 규칙이나 프로젝트 구조에 맞게 Swagger UI를 정돈할 수 있습니다.

 

---

6. Swagger 사용 시 주의사항

Swagger는 개발 및 테스트 환경에서 매우 유용하지만,
운영 환경에서는 보안 및 성능상의 이유로 주의가 필요합니다.

1. 운영 서버 비활성화
   Swagger는 테스트 용도로 제공되기 때문에, 운영 환경에서는 비활성화해야 합니다.
   예를 들어, @Profile("dev") 어노테이션을 사용하여 개발 환경에서만 Swagger 설정을 적용할 수 있습니다.
2. 민감한 데이터 노출 방지
   요청 및 응답 모델에 개인 정보나 보안 토큰이 포함되지 않도록 주의해야 합니다.
   Swagger 문서가 외부에 노출될 경우, 내부 데이터 구조가 그대로 드러날 위험이 있습니다.
3. 버전 관리
   프로젝트가 확장될수록 API 버전을 구분해 관리하는 것이 좋습니다.
   /v1/api, /v2/api와 같은 버전별 엔드포인트를 사용하거나
   @OpenAPIDefinition(info = @Info(version = "v1"))를 통해 명세 내에서 버전을 명시할 수 있습니다.

---

7. 결론

Swagger는 API 개발과 유지보수 과정에서 문서화와 테스트를 동시에 수행할 수 있는 강력한 도구입니다.
Spring Boot와의 통합이 간단하며, 코드 기반으로 문서가 자동 생성되므로 API 변경 사항을 문서에 수동으로 반영할 필요가 없습니다. 또한 Swagger UI를 통해 API의 요청과 응답을 직관적으로 확인할 수 있어 백엔드와 프론트엔드 간의 협업 효율을 높여줍니다.

결국 Swagger는 단순한 문서 생성기가 아니라, API 품질 관리와 협업의 생산성을 높이는 핵심 도구라고 할 수 있습니다.