Swagger와 연동한 스프링 REST API 문서 자동화 노하우

✅개요

REST API 문서화는 개발자들이 직면하는 가장 큰 도전 중 하나입니다. Swagger(OpenAPI)를 활용하면 스프링 부트 애플리케이션의 API 문서를 자동으로 생성하고 관리할 수 있습니다. 이 글에서는 Swagger를 스프링 부트와 연동하는 방법과 실제 프로젝트에서 활용할 수 있는 다양한 노하우를 공유합니다.

✅Swagger란?

Swagger(현재는 OpenAPI Specification)는 REST API를 설계, 빌드, 문서화 및 사용하기 위한 개방형 표준 명세입니다. API의 구조를 시각적으로 보여주며, 실시간으로 API를 테스트할 수 있는 인터페이스를 제공합니다.

 

✅프로젝트 설정

의존성 추가

최신 버전의 SpringDoc OpenAPI를 사용하기 위해 build.gradle에 다음 의존성을 추가합니다.

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

 

기본 설정

application.yml 파일에 Swagger UI 설정을 추가합니다.

 

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    groups-order: DESC
    operations-sorter: method
    disable-swagger-default-url: true

 

✅API 문서화 베스트 프랙티스

1. API 기본 정보 설정

SwaggerConfig 클래스를 생성하여 API 문서의 기본 정보를 설정합니다.

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
            .title("Spring REST API Documentation")
            .version("v1.0")
            .description("스프링 부트 REST API 문서");
            
        return new OpenAPI()
            .info(info)
            .externalDocs(new ExternalDocumentation()
                .description("추가 문서")
                .url("https://example.com/docs"));
    }
}

 

2. Controller 문서화

컨트롤러 클래스와 메서드에 상세한 설명을 추가합니다.

@Tag(name = "User API", description = "사용자 관리 API")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(
        summary = "사용자 정보 조회",
        description = "사용자 ID로 상세 정보를 조회합니다.",
        responses = {
            @ApiResponse(
                responseCode = "200",
                description = "조회 성공",
                content = @Content(schema = @Schema(implementation = UserResponse.class))
            ),
            @ApiResponse(
                responseCode = "404",
                description = "사용자를 찾을 수 없음"
            )
        }
    )
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        // 구현 내용
    }
}

 

3. DTO 문서화

데이터 모델에 대한 상세한 설명을 추가합니다.

@Schema(description = "사용자 응답 DTO")
public class UserResponse {
    
    @Schema(description = "사용자 ID", example = "1")
    private Long id;
    
    @Schema(description = "사용자 이름", example = "홍길동")
    private String name;
    
    @Schema(description = "이메일 주소", example = "hong@example.com")
    private String email;
}

 

✅고급 설정 및 팁

1. API 그룹화

여러 API를 논리적 그룹으로 구분합니다.

@Tags(value = {
    @Tag(name = "Group1", description = "그룹1 API"),
    @Tag(name = "Group2", description = "그룹2 API")
})

 

2. 보안 설정

인증이 필요한 API에 보안 설정을 추가합니다.

@SecurityRequirement(name = "bearerAuth")
@Operation(summary = "인증된 사용자 정보 조회")

 

3. 응답 예시 추가

실제 응답 예시를 문서에 포함시킵니다.

@ApiResponse(
    responseCode = "200",
    content = {
        @Content(
            mediaType = "application/json",
            examples = {
                @ExampleObject(
                    name = "success",
                    value = """
                    {
                        "id": 1,
                        "name": "홍길동",
                        "email": "hong@example.com"
                    }
                    """
                )
            }
        )
    }
)

 

✅마치며

Swagger를 활용한 API 문서 자동화는 개발 생산성을 크게 향상시킬 수 있습니다.

문서화를 코드와 함께 관리함으로써 항상 최신 상태를 유지할 수 있으며, 팀 간 협업을 원활하게 만들어줍니다.

위의 베스트 프랙티스를 따르면서 프로젝트의 특성에 맞게 커스터마이징하면 효과적인 API 문서화를 달성할 수 있습니다.