Swagger

Swagger 가이드

API 명세의 필요성

프로젝트에서 Frontend와 Backend 개발자 간의 원활한 협업을 위해서는 API 명세가 필수적입니다. API 명세는 엔드포인트, 요청/응답 형식, 데이터 구조 등을 명확하게 정의하여 개발 과정에서의 혼란을 줄이고 생산성을 향상시킵니다. 또한 API 문서화를 통해 새로운 팀원의 온보딩 시간을 단축하고, 프로젝트 유지보수성을 높일 수 있습니다.

Swagger 소개

Swagger(현재는 OpenAPI Specification)는 REST API를 설계, 문서화, 테스트할 수 있는 오픈소스 프레임워크입니다. Java 기반의 Spring Boot 프로젝트에서는 Springfox 또는 SpringDoc 라이브러리를 통해 Swagger를 쉽게 통합할 수 있습니다. Swagger UI를 통해 API를 시각적으로 확인하고 직접 테스트해볼 수 있으며, JSON/YAML 형식으로 API 명세를 관리할 수 있습니다.

주요 Swagger 기능과 애노테이션

• @Tag: API 그룹화를 위한 애노테이션으로, 컨트롤러 클래스 레벨에서 사용하여 관련 API들을 카테고리화합니다.
• @Operation: API 엔드포인트에 대한 상세 설명을 제공하며, 메서드 레벨에서 사용됩니다. summary, description 등을 정의할 수 있습니다.
• @Parameter: API 요청 파라미터에 대한 설명을 추가합니다. 파라미터의 이름, 설명, 필수 여부 등을 정의할 수 있습니다.
• @Schema: DTO 클래스의 필드에 대한 상세 정보를 정의합니다. 필드의 설명, 예시 값, 제약조건 등을 명시할 수 있습니다.
• @ApiResponse: API 응답에 대한 설명을 제공합니다. 상태 코드별 응답 형식과 설명을 정의할 수 있습니다.

사용 예시

기본 설정

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
            .title("Spring Boot API Documentation")
            .version("v1.0")
            .description("Spring Boot REST API 명세서");

        return new OpenAPI()
            .info(info);
    }
}

Controller 작성

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

    @Operation(summary = "사용자 조회", description = "사용자 ID로 정보를 조회합니다.")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "조회 성공"),
        @ApiResponse(responseCode = "404", description = "사용자 없음")
    })
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(
        @Parameter(description = "사용자 ID") @PathVariable Long id) {
        // 구현 로직
    }
}

DTO 작성

@Schema(description = "사용자 요청 DTO")
public class UserRequest {
    @Schema(description = "사용자 이름", example = "홍길동")
    @NotBlank
    private String name;

    @Schema(description = "이메일", example = "hong@gmail.com")
    @Email
    private String email;
}

API 명세서 작성 방법

1. 기본 정보 정의

• API 제목, 설명, 버전 등 기본 정보를 설정
• 서버 정보(개발/운영) 명시

2. API 그룹화

• 기능별로 API를 그룹화하여 구조화된 문서 작성
• 각 그룹에 대한 설명 추가

3. 상세 API 명세

• HTTP 메서드, 엔드포인트 경로 기술
• 요청/응답 데이터의 스키마 정의
• 예상되는 오류 상황과 응답 문서화

4. 예시 추가

• 요청/응답의 예시를 포함하여 이해를 돕기
• 실제 사용 사례를 기반으로 예시 작성

장단점

장점

• 직관적인 UI를 통한 API 테스트 가능
• 자동화된 문서 생성으로 유지보수 용이
• 프론트엔드와 백엔드 개발자 간 효율적인 협업 가능
• API 설계의 표준화 달성

단점

• 애노테이션 사용으로 인한 코드 복잡도 증가
• 상세한 설정을 위해서는 추가적인 학습 필요
• 프로덕션 환경에서 보안 위험 가능성
• 애노테이션 과다 사용시 코드 가독성 저하

참고 자료

• Swagger 공식 문서: https://swagger.io/docs/
• SpringDoc 문서: https://springdoc.org/
• OpenAPI Specification: https://spec.openapis.org/oas/latest.html