Swagger 가이드

Swagger UI 접속

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

의존성

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

application.yml 설정

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

Controller 레벨: @Tag

// 형식: @Tag(name = "{순번}. {API명}", description = "...")
@Tag(name = "1. 예약 API", description = "예약 등록, 조회, 수정, 삭제 API")
@RestController
@RequiredArgsConstructor
@Slf4j
@RequestMapping("/api/reservation")
public class ReservationController {
    // ...
}

메서드 레벨: @Operation, @ApiResponse

@Operation(
    summary = "예약 단건 조회",
    description = "예약 일련번호로 예약 상세 정보를 조회합니다."
)
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "조회 성공"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    @ApiResponse(responseCode = "500", description = "서버 오류")
})
@PostMapping("/get")
public ResponseJson<ReservationVo> get(@RequestBody ReservationVo vo) {
    return ResponseJson.success(reservationService.get(vo));
}

VO 레벨: @Schema

VO 클래스와 필드에 @Schema를 적용한다.

@Schema(description = "예약 VO")
@Getter
@Setter
@ToString
public class ReservationVo extends GeneralVO {

    @Schema(description = "예약 일련번호", example = "12345")
    private Long reservationSn;

    @Schema(description = "예약자 이름", example = "홍길동",
            requiredMode = Schema.RequiredMode.REQUIRED,
            minLength = 1, maxLength = 50)
    @RequiredField
    @MaxLength(50)
    private String reserverNm;

    @Schema(description = "예약일시", example = "20260516143000",
            format = "yyyyMMddHHmmss")
    @ValidDateTime
    private String reservationDt;
}

@Schema 속성 정리

OpenAPI 전역 설정

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("개발 가이드 API")
                        .description("개발 가이드 웹사이트 API 명세")
                        .version("v1.0.0"))
                .components(new Components()
                        .addSecuritySchemes("bearerAuth",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

운영 환경 Swagger 비활성화

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

체크리스트

• [ ] Swagger UI 접속 URL: http://localhost:8080/swagger-ui/index.html
• [ ] Controller: @Tag(name = "{순번}. {API명}", description = "...")
• [ ] 메서드: @Operation, @ApiResponse 적용
• [ ] VO: @Schema(description, example, requiredMode, minLength, maxLength, format) 적용
• [ ] 운영 환경 Swagger 비활성화 설정