Spring Boot에서 OpenAPI 스키마 자동 생성과 커스터마이징

개요

Spring Boot 프로젝트에 OpenAPI 스키마를 자동으로 생성하면 문서화가 쉬워진다. 또한 자동 생성 결과를 그대로 두면 부족한 점이 생긴다. 이 글에서는 springdoc을 사용해 스키마를 자동생성하고, OpenApiCustomiser와 어노테이션을 이용해 커스터마이징하는 실무 패턴을 정리한다. 초보자도 따라할 수 있도록 단계와 예제를 제공한다.

사전 준비

다음이 필요하다.

• Spring Boot 2.6+ 또는 3.x
• springdoc-openapi 라이브러리
• 간단한 REST 컨트롤러와 DTO

설치 및 기본 설정

Maven 의존성을 추가한다. 코드 블록에서는 XML의 < >를 이스케이프한다.

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

application.yml에 기본 정보를 넣는다.

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
info:
  title: Sample API
  version: 1.0.0

자동 생성 동작 원리

springdoc은 컨트롤러와 DTO의 구조를 읽어 OpenAPI 스키마를 만든다. 메서드의 반환 타입, 파라미터 어노테이션, @Schema 어노테이션을 함께 사용하면 더 정확한 문서가 생성된다. 다만 자동 생성만으로는 다음과 같은 요구를 모두 충족하기 어렵다.

• 전역 공통 응답 설명
• 보안 스키마 정의와 전역 적용
• 타입 이름 충돌 해결 또는 별칭 지정
• 특정 엔드포인트에 대한 추가 메타데이터 주입

스키마 커스터마이징 방법

주요 방법은 다음 세 가지다.

• DTO에 @Schema 어노테이션 적용
• OpenApiCustomiser 빈으로 OpenAPI 객체 수정
• OperationCustomizer 또는 OperationFilter로 개별 엔드포인트 수정

@Schema로 모델 세부 조정

필드별 설명, 예시, null 허용 여부 등을 어노테이션으로 명시한다. 모델 자체의 이름을 바꾸거나 설명을 추가할 수 있다.

public class UserDto {
  @io.swagger.v3.oas.annotations.media.Schema(description = "사용자 아이디", example = "john")
  private String username;

  @io.swagger.v3.oas.annotations.media.Schema(description = "이메일 주소", example = "john@example.com")
  private String email;

  // getters/setters
}

OpenApiCustomiser로 전역 수정

OpenApiCustomiser 빈은 생성된 OpenAPI 모델을 코드로 조작할 때 유용하다. 전역 보안 스키마를 추가하거나, 스키마 이름을 일괄 변경할 수 있다.

@org.springframework.context.annotation.Configuration
public class OpenApiConfig {

  @org.springframework.context.annotation.Bean
  public org.springdoc.core.customizers.OpenApiCustomiser customOpenApi() {
    return openApi -> {
      // 보안 스키마 추가
      openApi.getComponents()
        .addSecuritySchemes("bearerAuth",
          new io.swagger.v3.oas.models.security.SecurityScheme()
            .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.HTTP)
            .scheme("bearer").bearerFormat("JWT"));

      // 전역 보안 요구사항 적용
      openApi.addSecurityItem(new io.swagger.v3.oas.models.security.SecurityRequirement().addList("bearerAuth"));

      // 스키마 이름 충돌 해결 예시
      openApi.getComponents().getSchemas().forEach((name, schema) -> {
        if (name.contains("Map")) {
          schema.setTitle("MapWrapper");
        }
      });
    };
  }
}

OperationCustomizer로 엔드포인트 수준 수정

특정 컨트롤러 메서드에 대해 응답 헤더를 추가하거나, 상태 코드별 설명을 보강할 때 사용한다.

@org.springframework.context.annotation.Bean
public org.springdoc.core.customizers.OperationCustomizer customizeOperation() {
  return (operation, handlerMethod) -> {
    if (handlerMethod.getMethod().getName().equals("getSensitive")) {
      operation.addParametersItem(new io.swagger.v3.oas.models.parameters.Parameter()
        .name("X-Request-ID").required(false).in("header"));
    }
    return operation;
  };
}

실무 적용 팁

설계와 문서는 분리한다. DTO는 실제 응답 구조를 반영하고, @Schema로 설명을 채운다. OpenApiCustomiser는 보안, 공통 응답, 스키마 네이밍 규칙을 중앙에서 관리하는 용도로 사용한다. 또한 CI 파이프라인에서 API 문서 검증 단계를 둬 변경 사항이 문서에 반영되는지 확인한다.

버전 관리와 호환성

스키마 변경은 클라이언트에 영향을 준다. 변경 시 버전 전략을 세우고, 스키마에 deprecated 속성을 넣어 이전 소비자를 안내한다. OpenApiCustomiser를 이용해 오래된 모델은 유지하면서 새로운 모델을 추가하는 방식이 유용하다.

결론

springdoc을 쓰면 Spring Boot에서 OpenAPI 스키마 자동생성과 커스터마이징이 수월해진다. DTO 어노테이션으로 세부를 채우고, OpenApiCustomiser와 OperationCustomizer로 전역·엔드포인트 수준 조정을 하면 운영 환경에서도 관리성이 높아진다. 작은 설정만으로도 문서의 정확도와 신뢰도를 크게 개선할 수 있다.