---
id: api-openapi-spec
title: OpenAPI / Swagger — Schema-first vs Code-first
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [api, openapi, swagger, vibe-coding]
tech_stack: { language: "TS / OpenAPI", applicable_to: ["Backend"] }
applied_in: []
aliases: [OpenAPI, Swagger, schema-first, code-first, Hono RPC, oRPC, ts-rest]
---

# OpenAPI

> API contract 표준. **Schema → Type generation, mock server, client SDK, docs**. Schema-first 또는 Code-first. **Hono / ts-rest / oRPC** 가 modern code-first.

## 📖 핵심 개념
- OpenAPI 3.1: 표준 spec.
- Schema-first: yaml/json 먼저 → 코드 생성.
- Code-first: 코드의 type → spec 자동.
- Server / client SDK 자동.

## 💻 코드 패턴

### Schema-first (yaml)
```yaml
openapi: 3.1.0
info:
  title: Acme API
  version: 1.0.0

paths:
  /orders:
    get:
      summary: List orders
      parameters:
        - { name: limit, in: query, schema: { type: integer, default: 20 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
    post:
      summary: Create order
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrder' }
      responses:
        '201':
          description: created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '400':
          description: validation error
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }

components:
  schemas:
    Order:
      type: object
      required: [id, items, total]
      properties:
        id: { type: string, format: uuid }
        items:
          type: array
          items: { $ref: '#/components/schemas/OrderItem' }
        total: { type: string }
        status: { type: string, enum: [open, paid, shipped] }
    
    Problem:
      type: object
      required: [type, title, status]
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
```

### 코드 생성
```bash
# Server stub
openapi-generator-cli generate -i api.yaml -g typescript-node-server -o server/

# Client SDK
openapi-generator-cli generate -i api.yaml -g typescript-axios -o client/

# 또는 modern: openapi-typescript
npx openapi-typescript api.yaml -o api-types.ts
```

```ts
import type { paths } from './api-types';
type CreateOrderRequest = paths['/orders']['post']['requestBody']['content']['application/json'];
type OrderResponse = paths['/orders']['post']['responses']['201']['content']['application/json'];
```

### Code-first — Hono + zod-openapi
```ts
import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';

const app = new OpenAPIHono();

const route = createRoute({
  method: 'post',
  path: '/orders',
  request: {
    body: {
      content: { 'application/json': { schema: CreateOrderSchema } },
    },
  },
  responses: {
    201: {
      content: { 'application/json': { schema: OrderSchema } },
      description: 'Created',
    },
  },
});

app.openapi(route, async (c) => {
  const data = c.req.valid('json'); // typed
  const order = await createOrder(data);
  return c.json(order, 201);
});

// Spec 노출
app.doc('/openapi.json', { openapi: '3.1.0', info: { title: 'API', version: '1.0' } });
```

### Code-first — ts-rest
```ts
import { initContract } from '@ts-rest/core';
const c = initContract();

export const contract = c.router({
  createOrder: {
    method: 'POST',
    path: '/orders',
    body: CreateOrderSchema,
    responses: { 201: OrderSchema, 400: ProblemSchema },
  },
});

// Server (Express / Fastify / Hono)
import { initServer } from '@ts-rest/express';
const router = initServer().router(contract, {
  createOrder: async ({ body }) => ({ status: 201, body: await create(body) }),
});

// Client (auto-typed)
import { initClient } from '@ts-rest/core';
const api = initClient(contract, { baseUrl: '...' });
const r = await api.createOrder({ body: { items: [...] } });
```

→ Frontend / backend 가 type 공유.

### Mock server (fast prototyping)
```bash
# Prism — OpenAPI mock
prism mock api.yaml --port 4010
```

→ Backend 만들기 전에 frontend 시작.

### Docs UI
```ts
// Swagger UI
import swaggerUi from 'swagger-ui-express';
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec));

// Scalar (modern, beautiful)
import { apiReference } from '@scalar/express-api-reference';
app.use('/docs', apiReference({ spec: { url: '/openapi.json' } }));

// Stoplight Elements
```

### Validation (Hono / Express middleware)
```ts
// Express
import OpenApiValidator from 'express-openapi-validator';
app.use(OpenApiValidator.middleware({ apiSpec: 'api.yaml' }));
// 자동 validate body / query / response
```

### Lint (Spectral)
```bash
npx spectral lint api.yaml
# 표준 / 일관성 검사
```

```yaml
# .spectral.yml
rules:
  operation-tag-defined: warn
  operation-success-response: error
  no-unresolved-refs: error
```

### Diff (breaking change)
```bash
npx oasdiff diff old.yaml new.yaml --breaking-only
# CI 에서 PR 마다
```

### Code-first vs Schema-first
```
Schema-first:
+ Single source of truth
+ Multi-language (server / client)
- Sync 어려움 (yaml 과 코드)

Code-first:
+ TS type 가 진실
+ Hot reload
- 다른 언어 client = generate 필요
```

## 🤔 의사결정 기준
| 상황 | 추천 |
|---|---|
| TS only fullstack | ts-rest / oRPC / Hono RPC / tRPC |
| 다양한 client 언어 | Schema-first OpenAPI |
| Public API | OpenAPI + Scalar docs |
| Mock first | Schema-first + Prism |
| Strong type 일급 | Code-first |
| 빠른 prototype | Code-first |

## ❌ 안티패턴
- **Spec 과 코드 drift**: schema-first 의 위험. CI 에서 검증.
- **모든 endpoint 200 만 명시**: 4xx / 5xx 같이.
- **Schema 안 example**: 사용자 모름.
- **Auth 누락 (security scheme)**: 명시.
- **Generated client 직접 변경**: 다음 generate 시 잃음.
- **OpenAPI 안 서버 검증**: client 만 — server bypass 가능.
- **Versioning 없는 spec 변경**: breaking.

## 🤖 LLM 활용 힌트
- TS = ts-rest / Hono RPC.
- 다중 언어 = OpenAPI yaml + generators.
- Spectral lint + oasdiff CI.

## 🔗 관련 문서
- [[API_REST_Best_Practices]]
- [[API_Versioning_Strategies]]
- [[TS_Schema_Validation_Comparison]]