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();
    }
}

공통 application.yaml은 springdoc.api-docs.enabled: ${swagger.enabled}로 커스텀 프로퍼티를 참조하고, 값은 프로파일별 yaml이 채운다. test에서만 끄고 local/prod/docker에서는 켠다. 데모 배포라 prod도 API 문서를 공개한다.
config/test/application-test.yaml
```
swagger:
  enabled: false
```
config/prod/application-prod.yaml
```
swagger:
  enabled: true
```

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

클래스에 @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