Swagger / API 문서화

현재 상태

이 프로젝트는 현재 Swagger/OpenAPI 의존성이 추가되어 있지 않다.
API 문서화가 필요할 경우 아래 가이드를 참고하여 적용한다.

의존성 추가

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

기본 설정

# application.yml
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui/index.html
    operations-sorter: method
    tags-sorter: alpha
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

Swagger UI 접근: http://localhost:8080/swagger-ui/index.html

OpenAPI Bean 설정

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Scraping Agent API")
                        .version("v1.0.0")
                        .description("뉴스 수집 및 다이제스트 생성 서비스 API"))
                .externalDocs(new ExternalDocumentation()
                        .description("개발 가이드")
                        .url("http://localhost:8080/guide"));
    }
}

컨트롤러 어노테이션 예시

@Tag(name = "Notes API", description = "노트 관리 API")
@RestController
@RequestMapping("/api/v1/posts")
@RequiredArgsConstructor
public class PostApiController {

    @Operation(
        summary = "노트 등록",
        description = "새 노트를 등록한다.",
        responses = {
            @ApiResponse(responseCode = "201", description = "등록 성공"),
            @ApiResponse(responseCode = "400", description = "입력값 오류")
        }
    )
    @PostMapping
    public ResponseEntity<ApiResponse<PostDetailRes>> regPost(
            @RequestBody @Valid PostCreateReq req) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(ApiResponse.ok(postService.regPost(req)));
    }

    @Operation(summary = "노트 단건 조회")
    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<PostDetailRes>> getPost(
            @Parameter(description = "노트 ID", example = "1")
            @PathVariable Long id) {
        return ResponseEntity.ok(ApiResponse.ok(postService.getPost(id)));
    }
}

VO 문서화

@Schema(description = "노트 등록 요청")
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class PostCreateReq {

    @Schema(description = "제목", example = "Spring Boot 시작하기", maxLength = 200)
    @NotBlank(message = "제목은 필수입니다.")
    @Size(max = 200)
    private String title;

    @Schema(description = "내용", example = "Spring Boot는 ...")
    @NotBlank(message = "내용은 필수입니다.")
    private String content;

    @Schema(description = "카테고리", example = "BACKEND",
            allowableValues = {"BACKEND", "AI", "DEVOPS"})
    @NotBlank(message = "카테고리는 필수입니다.")
    private String category;
}

운영 환경 Swagger 비활성화

# application-prod.yml
springdoc:
  api-docs:
    enabled: false   # 운영 환경에서 API 문서 비활성화
  swagger-ui:
    enabled: false

보안 고려사항

• 운영 환경에서는 Swagger UI를 반드시 비활성화한다.
• 인증이 필요한 API는 Swagger UI에서도 인증 후 테스트할 수 있도록 설정한다.
• /api-docs, /swagger-ui/** 엔드포인트는 운영 환경에서 접근 차단한다.

체크리스트

• [ ] 운영 환경 (prod 프로파일) Swagger 비활성화
• [ ] API 경로에 민감 정보 포함 금지
• [ ] 모든 주요 엔드포인트에 @Operation 설명 작성
• [ ] 응답 코드 명시 (@ApiResponse)