Swagger 가이드

springdoc-openapi-starter-webmvc-ui 라이브러리로 API 명세를 Swagger UI로 제공한다.

설정

의존성 추가

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.0'
}

OpenAPI 기본 정보와, 기능별로 묶어 보기 위한 GroupedOpenApi를 빈으로 등록한다.

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        final Info info =
                new Info().title("Dictionary").version("v1").description("Dictionary API 명세");
        return new OpenAPI().info(info);
    }

    @Bean
    public GroupedOpenApi allApi() {
        return GroupedOpenApi.builder().group("00. All").pathsToMatch("/v1/**").build();
    }

    @Bean
    public GroupedOpenApi groupBoard() {
        return GroupedOpenApi.builder()
                .group("06. CRUD Template")
                .pathsToMatch("/v1/board/**")
                .build();
    }
}

swagger.enabled 프로퍼티로 노출 여부를 프로파일별로 제어한다 — local에서만 열어두고 test/prod에서는 닫는다.
config/local/application-local.yaml
```
springdoc:
  swagger-ui:
    enabled: true
```
config/prod/application-prod.yaml
```
springdoc:
  swagger-ui:
    enabled: false
```

컨트롤러 문서화 애노테이션

클래스에 @Tag(name, description)을 붙인다(기능 이름을 한글로).

@Tag(name = "게시판(CRUD 템플릿)", description = "게시판(CRUD 템플릿) API")
@RestController
@RequestMapping("/v1/board")
public class BoardController extends AbstractController { ... }

각 메소드에 @Operation(summary, description)을 붙인다.

@Operation(summary = "게시판 데이터 등록", description = "게시판 데이터 등록 API")
@ApiResponse(responseCode = "201", description = "게시글 등록 성공(Location 헤더 포함)")
@PostMapping
public @ResponseBody ResponseEntity<ResponseDto<BoardResponseDto>> create(
        @Valid @RequestBody final RequestDto<BoardCreateRequestDto> request) { ... }

기본 상태 코드(200)를 벗어나는 경우(201/204)는 @ApiResponse(responseCode, description)으로 명시한다.

DTO 필드는 @Schema(description, example)로 설명·예시값을 남긴다.

@Schema(description = "제목", example = "금상")
@NotBlank
private String title;

확인 경로

Swagger UI: local swagger
OpenAPI 스펙(JSON): http://localhost:8080/v3/api-docs