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를 만들었습니다. 사용한 스택은 다음과 같습니다.
org.openapi.generator Gradle 플러그인 7.23.0엔드포인트 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에서 꽤 유용한 부분입니다.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에서 생성되어 있습니다.
이제 직접 할 일은 이 인터페이스를 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이었습니다. 빌드가 통과한다고 구현이 끝난 것은 아니라는 점을 이 구조에서는 한 번 짚고 넘어갈 만합니다.
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지정만 사용하는 편이 맞았습니다.
이 워크플로의 효용을 확인하기 좋은 실험이 하나 있습니다. listTodos에 쿼리 파라미터 limit을 스펙에 추가하고 다시 컴파일해 보는 것입니다.
- name: limit
in: query
schema:
type: integer
./gradlew compileJava를 실행하면 컴파일 에러가 납니다. 생성된 TodoApi.listTodos의 시그니처가 (TodoStatus, Integer)로 바뀌었는데, 컨트롤러는 아직 (TodoStatus)라서 @Override가 맞지 않기 때문입니다.
스펙과 구현의 불일치가 런타임이 아니라 빌드 단계에서 드러난다는 점이 이 방식의 실질적인 이득이라고 생각합니다. 문서만 바꾸고 구현을 손대지 않는 상황이 컴파일러 선에서 막히므로, 문서와 서버 인터페이스, 검증이 함께 움직이게 됩니다.
generatorName = 'typescript-axios'나 'java'로 태스크를 하나 더 두면, 프런트엔드나 다른 서비스가 쓰는 호출 코드도 동일한 스펙에서 생성됩니다. 양쪽이 같은 계약을 공유하게 됩니다.openApiGenerate와 compileJava를 돌리면, 스펙과 구현이 어긋나는 변경이 들어올 때 빌드가 실패합니다.build/ 아래 생성물은 .gitignore 대상으로 두고 스펙만 버전 관리했습니다. 생성된 코드를 직접 수정해도 다음 빌드에서 덮어쓰이므로, 고칠 부분이 있으면 스펙을 고치는 쪽이 맞다고 봅니다.작은 Todo API로 해 본 실습이라 규모는 작았지만, 엔드포인트가 늘고 클라이언트가 여러 개 붙는 상황일수록 문서·서버·클라이언트를 한 파일에서 묶어 두는 이득과, 보일러플레이트를 생성기에 맡기고 직접 작성하는 범위를 비즈니스 로직으로 좁힐 수 있다는 이득이 함께 커질 것으로 생각합니다.