springdoc-openapi로 API 문서 1분 셋업

springdoc-openapi로 API 문서 1분 셋업

Spring Boot 3에서 springdoc-openapi를 사용하면 Swagger UI까지 몇 줄로 구성할 수 있습니다. 기본 설정 → 그룹/보안 스키마 → 예시 어노테이션 순으로 정리합니다.

의존성

// build.gradle.kts
dependencies {
  implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")
}

접속 경로

• Swagger UI: /swagger-ui.html
• OpenAPI JSON: /v3/api-docs (그룹 사용 시 /v3/api-docs/{group})

그룹/패키지별 문서화

@Configuration
public class OpenApiConfig {
  @Bean
  public GroupedOpenApi apiV1() {
    return GroupedOpenApi.builder()
      .group("v1")
      .packagesToScan("com.example.api.v1")
      .pathsToMatch("/api/v1/**")
      .build();
  }
}

보안 스키마(JWT 예시)

@Configuration
class OpenApiSecurity {
  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
      .info(new Info().title("Example API").version("v1"))
      .components(new Components().addSecuritySchemes("BearerAuth",
        new SecurityScheme().name("Authorization")
          .type(SecurityScheme.Type.HTTP)
          .scheme("bearer").bearerFormat("JWT")))
      .addSecurityItem(new SecurityRequirement().addList("BearerAuth"));
  }
}

컨트롤러 어노테이션

@RestController
@RequestMapping("/api/v1/users")
class UserController {
  @Operation(summary = "사용자 조회", description = "ID로 사용자 상세를 조회합니다.")
  @ApiResponses({
    @ApiResponse(responseCode = "200", description = "성공",
      content = @Content(schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "404", description = "없음")
  })
  @GetMapping("/{id}")
  public User find(@PathVariable Long id) { ... }
}

문서 품질 팁

• @Schema로 필드 설명/예시(example) 작성
• 에러 응답은 공통 DTO로 규격화하고 전역 적용
• 그룹을 버전/도메인별로 나누어 탐색성 향상

 

⏪ 이전 글 보기: Jackson 직·역직렬화 어노테이션 핵심(@Json*)

 

👉 1편: Dockerfile 멀티스테이지로 이미지 절반 만들기

👉 2편: GitHub Actions: push 시 테스트 자동화 YAML

👉 3편: Jackson 직·역직렬화 어노테이션 핵심(@Json*)

👉 4편: springdoc-openapi로 API 문서 1분 셋업