🌱

OpenAPI 스펙으로 Spring API 코드 생성하기

최민석·2026-06-12

OpenAPI 스펙으로 Spring API 코드 생성하기

YAML로 API 스펙을 먼저 작성하고, 그 스펙에서 Java 인터페이스와 DTO, Swagger 문서를 생성하는 spec-first 워크플로를 직접 만들어보았습니다. Spring Boot 3.5와 openapi-generator를 사용했습니다.

API를 개발할 때 실제로 관리하게 되는 산출물은 보통 세 가지입니다. 이 API가 무엇을 받고 무엇을 돌려주는지 적은 문서, 컨트롤러 시그니처와 검증이 들어가는 서버 코드, 그리고 호출하는 쪽의 클라이언트 코드입니다. 이 셋이 따로 관리되면 시간이 지날수록 서로 어긋나기 쉽습니다. 컨트롤러를 고치고 문서는 따로 갱신하고, 프런트엔드에는 변경 사항을 별도로 공유하는 식이면 어딘가는 결국 옛 상태로 남습니다.

스펙 우선(spec-first) 방식은 이 순서를 바꿔서, 사람이 직접 작성하는 것을 OpenAPI 스펙 한 파일로 좁히고 나머지는 거기서 생성합니다.

openapi.yaml  ← 사람이 작성하는 단일 진실 공급원(single source of truth)
   │
   ├─ openapi-generator ─→ 서버 인터페이스 + DTO (Java)
   ├─ openapi-generator ─→ 클라이언트 SDK (TypeScript, Python 등)
   └─ Swagger UI         ─→ 문서 (YAML 그대로 렌더링)

문서와 서버, 클라이언트가 같은 파일에서 파생되므로 구조적으로 어긋날 여지가 줄어듭니다. 이 점이 spec-first를 선택하는 가장 큰 이유라고 생각합니다.

실습으로는 간단한 Todo CRUD API를 만들었습니다. 사용한 스택은 다음과 같습니다.

  • Spring Boot 3.5.15 / Java 21
  • org.openapi.generator Gradle 플러그인 7.23.0
  • springdoc-openapi 2.8.17 (Swagger UI)

1. 스펙 먼저 작성하기

엔드포인트 5개(GET/POST /todos, GET/PUT/DELETE /todos/{todoId})와 스키마 5개(Todo, TodoStatus, TodoCreateRequest, TodoUpdateRequest, ErrorResponse)를 OpenAPI 3 문서로 정의했습니다. 생성 요청 부분만 발췌하면 다음과 같습니다.

paths:
  /todos:
    post:
      operationId: createTodo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TodoCreateRequest'
      responses:
        '201':
          description: 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Todo'
components:
  schemas:
    TodoCreateRequest:
      type: object
      required: [title]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 1000

여기서 두 가지를 눈여겨봤습니다.

  • operationId는 생성될 Java 메서드 이름(createTodo)이 됩니다. 빠뜨리면 생성기가 경로 기반으로 메서드 이름을 임의로 만들기 때문에 지정해 두는 편이 좋습니다.
  • minLength, maxLength 같은 제약은 뒤에서 @Size 같은 Bean Validation 어노테이션으로 변환됩니다. 검증 규칙을 스펙에 적어 둔다는 점이 spec-first에서 꽤 유용한 부분입니다.

2. 생성기 설정하기 (build.gradle)

plugins {
    id 'org.springframework.boot' version '3.5.15'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'org.openapi.generator' version '7.23.0'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.17'
}

openApiGenerate {
    generatorName = 'spring'
    inputSpec  = "$rootDir/src/main/resources/static/openapi.yaml"
    outputDir  = "build/generated/openapi"
    apiPackage   = 'me.minseoky.codegen.api'
    modelPackage = 'me.minseoky.codegen.dto'
    configOptions = [
        interfaceOnly    : 'true',   // 컨트롤러 구현체가 아니라 인터페이스만 생성
        useSpringBoot3   : 'true',   // jakarta.* 네임스페이스
        useTags          : 'true',   // tag(todo)별로 인터페이스 분리 → TodoApi
        useBeanValidation: 'true',   // 스펙 제약 → @NotNull, @Size 등
        openApiNullable  : 'false',  // 불필요한 외부 의존성 회피
    ]
}

// 생성된 코드를 소스셋에 편입 + 컴파일 전에 생성이 돌도록 연결
sourceSets.main.java.srcDir layout.buildDirectory.dir('generated/openapi/src/main/java')
tasks.named('compileJava') { dependsOn tasks.openApiGenerate }

가장 중요한 옵션은 interfaceOnly: true입니다. 이 옵션을 켜면 생성기가 컨트롤러 구현체를 만들지 않고 인터페이스만 만듭니다. 비즈니스 로직은 직접 작성하되, URL 매핑과 검증, 문서 어노테이션 같은 보일러플레이트는 생성기가 맡는 분담이 됩니다.

마지막 두 줄도 빠뜨리면 안 됩니다. 생성된 코드는 build/ 아래에 떨어지는데, 이걸 srcDir로 소스셋에 등록하지 않으면 컴파일러가 찾지 못합니다. 그리고 compileJava.dependsOn openApiGenerate로 연결해 두어야 매 빌드마다 스펙에서 코드 생성이 먼저 돌게 됩니다.

./gradlew openApiGenerate를 실행하면 TodoApi.java와 DTO들이 생성됩니다. 생성된 인터페이스를 열어 보면 다음과 같은 모습입니다.

public interface TodoApi {

    @RequestMapping(method = RequestMethod.POST, value = "/todos",
                    produces = "application/json", consumes = "application/json")
    default ResponseEntity<Todo> createTodo(
        @Valid @RequestBody TodoCreateRequest todoCreateRequest
    ) {
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
    }
    // listTodos, getTodo, updateTodo, deleteTodo ...
}

@RequestMapping, @Valid, 응답 타입, 파라미터 바인딩이 직접 작성하지 않은 채 YAML에서 생성되어 있습니다.

3. 인터페이스 구현하기

이제 직접 할 일은 이 인터페이스를 implements 하고 로직을 채우는 것입니다.

@RestController
public class TodoController implements TodoApi {

    private final Map<Long, Todo> todos = new ConcurrentHashMap<>();
    private final AtomicLong counter = new AtomicLong(1);

    @Override
    public ResponseEntity<Todo> createTodo(TodoCreateRequest req) {
        Todo todo = new Todo(counter.getAndIncrement(), req.getTitle(),
                             TodoStatus.PENDING, OffsetDateTime.now())
                .description(req.getDescription());
        todos.put(todo.getId(), todo);
        return ResponseEntity.status(HttpStatus.CREATED).body(todo);
    }
    // 나머지 메서드도 @Override로 로직만 채웁니다
}

직접 해 보다가 한 번 걸렸던 지점이 있습니다. 생성된 인터페이스의 메서드는 전부 default 구현(501 NOT_IMPLEMENTED 반환)을 가지고 있어서, 메서드를 빼먹어도 컴파일이 통과합니다. createTodo 하나만 작성하고 빌드했더니 BUILD SUCCESSFUL이 떠서 다 된 줄 알았는데, 호출해 보니 나머지는 전부 501이었습니다. 빌드가 통과한다고 구현이 끝난 것은 아니라는 점을 이 구조에서는 한 번 짚고 넘어갈 만합니다.

4. Swagger UI를 스펙에 연결하기

springdoc은 기본적으로 런타임에 컨트롤러를 스캔해서 문서를 만듭니다. 다만 여기서는 이미 손으로 작성한 YAML이 있으므로, 그 파일을 그대로 보여주도록 설정했습니다.

springdoc.swagger-ui.url=/openapi.yaml

static/openapi.yaml은 Spring이 /openapi.yaml 경로로 자동 서빙하므로, Swagger UI가 이 URL을 읽으면 작성한 스펙이 그대로 문서가 됩니다.

💡 런타임 문서 생성을 끄겠다고 springdoc.api-docs.enabled=false를 넣으면 springdoc 자동설정 전체가 비활성화되어 Swagger UI까지 404가 됩니다. swagger-ui.url 지정만 사용하는 편이 맞았습니다.

5. 스펙을 바꾸면 구현이 컴파일 단계에서 깨진다

이 워크플로의 효용을 확인하기 좋은 실험이 하나 있습니다. listTodos에 쿼리 파라미터 limit을 스펙에 추가하고 다시 컴파일해 보는 것입니다.

- name: limit
  in: query
  schema:
    type: integer

./gradlew compileJava를 실행하면 컴파일 에러가 납니다. 생성된 TodoApi.listTodos의 시그니처가 (TodoStatus, Integer)로 바뀌었는데, 컨트롤러는 아직 (TodoStatus)라서 @Override가 맞지 않기 때문입니다.

스펙과 구현의 불일치가 런타임이 아니라 빌드 단계에서 드러난다는 점이 이 방식의 실질적인 이득이라고 생각합니다. 문서만 바꾸고 구현을 손대지 않는 상황이 컴파일러 선에서 막히므로, 문서와 서버 인터페이스, 검증이 함께 움직이게 됩니다.

실무로 확장한다면

  • 클라이언트 SDK 생성: 같은 YAML에 generatorName = 'typescript-axios'나 'java'로 태스크를 하나 더 두면, 프런트엔드나 다른 서비스가 쓰는 호출 코드도 동일한 스펙에서 생성됩니다. 양쪽이 같은 계약을 공유하게 됩니다.
  • CI에 생성과 컴파일 추가: PR마다 openApiGenerate와 compileJava를 돌리면, 스펙과 구현이 어긋나는 변경이 들어올 때 빌드가 실패합니다.
  • 생성 코드는 커밋하지 않기: build/ 아래 생성물은 .gitignore 대상으로 두고 스펙만 버전 관리했습니다. 생성된 코드를 직접 수정해도 다음 빌드에서 덮어쓰이므로, 고칠 부분이 있으면 스펙을 고치는 쪽이 맞다고 봅니다.

작은 Todo API로 해 본 실습이라 규모는 작았지만, 엔드포인트가 늘고 클라이언트가 여러 개 붙는 상황일수록 문서·서버·클라이언트를 한 파일에서 묶어 두는 이득과, 보일러플레이트를 생성기에 맡기고 직접 작성하는 범위를 비즈니스 로직으로 좁힐 수 있다는 이득이 함께 커질 것으로 생각합니다.

관련 포스트