OpenAPI 스펙을 손으로 작성하지 마세요

Source: Dev.to

수동 OpenAPI 사양의 문제점

API 문서를 작성하는 일은 지루합니다. 엔드포인트를 만든 뒤에는 곧바로 코드가 바뀔 때마다 금방 구식이 되는 YAML을 만들기 위해 몇 분을 소비하게 됩니다. 사양을 손으로 유지보수하면 다음과 같은 문제가 발생합니다:

• 중복된 스키마 정의
• 코드베이스와 동기화되지 않는 문서
• 각 엔드포인트마다 번거로운 YAML 편집

Codehooks.io 로 자동 OpenAPI 생성

Codehooks.io 를 사용하면 스키마를 한 번 정의하고 전체 OpenAPI 3.0 문서를 자동으로 생성할 수 있습니다.

스키마 정의하기

import { app } from 'codehooks-js';
import { z } from 'zod';

const todoSchema = z.object({
  title: z.string().min(1).max(200),
  completed: z.boolean().default(false),
  priority: z.enum(['low', 'medium', 'high'])
});

OpenAPI & Swagger UI 활성화

// Enable OpenAPI + Swagger UI
app.openapi({
  info: { title: 'Todo API', version: '1.0.0' }
});

CRUD 엔드포인트 자동 생성

// Auto-generate CRUD endpoints
app.crudlify({ todos: todoSchema });

export default app.init();

앱을 배포하고 /docs 를 방문하면 모든 CRUD 엔드포인트가 문서화된 완전한 인터랙티브 Swagger UI를 확인할 수 있습니다.

openapi() 미들웨어를 이용한 커스텀 엔드포인트

기본 CRUD를 넘어서는 라우트의 경우, OpenAPI 메타데이터를 직접 붙일 수 있습니다.

import { app, openapi } from 'codehooks-js';

app.get(
  '/stats',
  openapi({
    summary: 'Get statistics',
    tags: ['Analytics'],
    responses: {
      200: { description: 'Stats retrieved' }
    }
  }),
  async (req, res) => {
    res.json({ total: 42 });
  }
);

요청 본문에 Zod 스키마 사용하기

app.post(
  '/users',
  openapi({
    summary: 'Create user',
    requestBody: {
      content: {
        'application/json': { schema: UserSchema } // Zod schema auto‑converted
      }
    }
  }),
  handler
);

지원되는 스키마 형식

• Zod
• Yup
• JSON Schema

모두 자동으로 적절한 OpenAPI 정의로 변환됩니다.

주요 기능

• /docs 에서 Swagger UI 제공 (인증 지원 포함)
• 엔드포인트를 필터링하고 내부 라우트를 공개 문서에서 숨길 수 있음
• 중복 제로: 하나의 스키마가 검증과 문서화를 동시에 담당

설치

npm install codehooks-js@latest

시작하기

1. app.crudlify() 앞에 app.openapi() 를 추가합니다.
2. coho deploy 로 배포합니다.
3. /docs 에서 실시간 문서를 확인합니다.

더 이상 손으로 YAML을 작성할 필요가 없습니다. 더 이상 문서와 코드가 어긋나지 않습니다. 코드만 있으면 됩니다.

추가 자료

Full documentation: