Springdoc OpenAPI로 Spring Boot API 설명서 작성

개요

API를 명확히 표현하면 개발과 유지보수가 쉬워진다. Spring Boot 프로젝트에 Springdoc OpenAPI를 적용하면 코드 중심으로 OpenAPI 스펙을 만들고 Swagger UI로 탐색 가능한 인터페이스를 제공할 수 있다. 이 글은 처음 접하는 개발자도 이해하기 쉬운 단계로 설정부터 어노테이션 활용, 보안 연동까지 정리한다.

설치와 기본 설정

Maven 의존성

가장 흔한 방법은 springdoc-openapi-ui 의존성을 추가하는 방식이다.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>2.1.0</version>
</dependency>

Gradle 예시

implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0"

application.properties

기본적으로 별도 설정이 없어도 /swagger-ui/index.html 또는 /v3/api-docs 경로로 접근 가능하다. 기본 설정을 변경하려면 properties를 사용한다.

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

OpenAPI 커스터마이징

전역 메타데이터를 설정하려면 OpenAPI 빈을 만들면 된다. 이 빈으로 제목, 설명, 버전, 라이선스 등을 정의할 수 있다.

import org.springdoc.core.models.GroupedOpenApi;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
      .info(new Info().title("My API").version("v1").description("서비스 API 설명"));
  }

  @Bean
  public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
      .group("public")
      .pathsToMatch("/api/**")
      .build();
  }
}

컨트롤러 문서화

컨트롤러 수준에서 어노테이션을 붙이면 엔드포인트별 설명이 자동으로 추가된다. 주요 어노테이션은 @Operation, @Parameter, @ApiResponse 등이다.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Users", description = "사용자 관련 API")
@RestController
public class UserController {

  @Operation(summary = "모든 사용자 조회", description = "등록된 모든 사용자 목록을 반환")
  @ApiResponse(responseCode = "200", description = "정상 응답")
  @GetMapping("/api/users")
  public ResponseEntity<List<User>> getAllUsers() {
    // 구현
  }
}

응답 스키마 명세

모델 클래스에 @Schema 어노테이션을 쓰면 필드별 설명과 예시를 추가할 수 있다. 이렇게 하면 Swagger UI에서 구조를 명확히 볼 수 있다.

Swagger UI 사용법

서버를 띄운 뒤 브라우저에서 /swagger-ui/index.html 또는 설정한 경로로 접속하면 인터랙티브 문서가 나타난다. 요청을 테스트하고 응답을 확인할 수 있어 개발 속도가 빨라진다.

버전 관리와 그룹핑

API가 커질수록 그룹을 나누는 것이 유리하다. GroupedOpenApi를 사용하면 경로 기준으로 문서를 분리하고 버전별 UI를 제공할 수 있다.

보안(예: JWT) 통합

보안을 문서화하면 인증이 필요한 엔드포인트를 UI에서 바로 확인하고 토큰을 설정해 테스트할 수 있다. SecurityScheme을 OpenAPI에 추가하면 된다.

import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Bean
public OpenAPI securityOpenAPI() {
  return new OpenAPI()
    .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
    .components(new Components()
      .addSecuritySchemes("BearerAuth",
        new SecurityScheme()
          .type(SecurityScheme.Type.HTTP)
          .scheme("bearer")
          .bearerFormat("JWT")
      ));
}

팁과 주의사항

• 프로덕션 환경에서는 Swagger UI 노출을 제한하거나 인증을 적용한다.
• 대규모 스키마는 자동 생성 규칙을 검토해 불필요한 노출을 줄인다.
• 컨트롤러와 DTO에 주석을 충실히 작성하면 문서 품질이 좋아진다.

정리

Springdoc OpenAPI는 Spring Boot 환경에서 비교적 간단하게 API 설명서를 코드로 관리하게 해준다. 의존성 추가, OpenAPI 빈 등록, 컨트롤러 어노테이션 적용, Swagger UI 확인의 흐름으로 시작하면 된다. 보안이나 그룹핑 같은 확장 기능도 단계적으로 도입할 수 있다.