OpenAPI/Swagger 자동 문서화

pnpm add zod-openapi @asteasolutions/zod-to-openapi

// schemas/post.ts
import { z } from 'zod';
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
extendZodWithOpenApi(z);

export const PostSchema = z.object({
  id: z.string().openapi({ example: 'p_abc123' }),
  title: z.string().min(1).max(200).openapi({ example: '오늘의 글' }),
  content: z.string().openapi({ example: '본문...' }),
  authorId: z.string(),
  published: z.boolean(),
  createdAt: z.string().datetime(),
}).openapi('Post');

export const CreatePostSchema = PostSchema.pick({
  title: true, content: true,
}).openapi('CreatePost');

export const PostListSchema = z.object({
  items: z.array(PostSchema),
  nextCursor: z.string().nullable(),
}).openapi('PostList');

import { OpenAPIRegistry, OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';

const registry = new OpenAPIRegistry();

registry.registerPath({
  method: 'get',
  path: '/posts',
  description: '게시물 목록 조회 (cursor 페이지네이션)',
  summary: '게시물 목록',
  tags: ['Posts'],
  request: {
    query: z.object({
      limit: z.coerce.number().int().min(1).max(100).default(20),
      cursor: z.string().optional(),
    }),
  },
  responses: {
    200: {
      description: '게시물 목록',
      content: { 'application/json': { schema: PostListSchema } },
    },
    401: {
      description: '인증 실패',
      content: { 'application/problem+json': { schema: ProblemSchema } },
    },
  },
});

registry.registerPath({
  method: 'post',
  path: '/posts',
  description: '새 게시물 생성',
  tags: ['Posts'],
  security: [{ bearerAuth: [] }],
  request: {
    body: { content: { 'application/json': { schema: CreatePostSchema } } },
  },
  responses: {
    201: { description: '생성됨', content: { 'application/json': { schema: PostSchema } } },
    400: { description: '검증 실패', content: { 'application/problem+json': { schema: ProblemSchema } } },
  },
});


registry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer',
  bearerFormat: 'JWT',
});


// 문서 생성
const generator = new OpenApiGeneratorV31(registry.definitions);
const document = generator.generateDocument({
  openapi: '3.1.0',
  info: {
    title: 'My API',
    version: '1.0.0',
    description: '...',
  },
  servers: [{ url: 'https://api.example.com' }],
});


// 정적 파일 또는 동적 엔드포인트
fs.writeFileSync('openapi.json', JSON.stringify(document, null, 2));

import swaggerUi from 'swagger-ui-express';

app.get('/openapi.json', (req, res) => res.json(document));
app.use('/docs', swaggerUi.serve, swaggerUi.setup(document, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'My API Docs',
}));


// 또는 Scalar (모던 UI)
import { apiReference } from '@scalar/express-api-reference';

app.use('/docs', apiReference({
  spec: { url: '/openapi.json' },
  theme: 'purple',
}));

// 라우트 핸들러 — Zod로 검증 + OpenAPI 자동 생성
router.post('/posts', asyncHandler(async (req, res) => {
  const data = CreatePostSchema.parse(req.body);  // 동일 스키마
  const post = await postService.create(req.user!.id, data);
  res.status(201).json(post);
}));


// → 검증 실패 = 400 RFC 7807
// → 성공 = 201 + PostSchema
// → 문서와 실제 동작 100% 일치

# .github/workflows/api-docs.yml
- name: Generate OpenAPI
  run: pnpm generate:openapi

- name: Validate OpenAPI
  run: pnpm dlx @redocly/cli lint openapi.json

- name: Diff against main
  run: |
    git diff main openapi.json
    if [ $? -ne 0 ]; then
      echo "API spec changed - reviewer check required"
    fi

- name: Breaking change detection
  run: |
    pnpm dlx oasdiff breaking main:openapi.json HEAD:openapi.json

# TypeScript
pnpm dlx openapi-typescript openapi.json -o ./generated/api.ts


# 또는 풀 SDK
pnpm dlx @hey-api/openapi-ts -i openapi.json -o ./generated -c @hey-api/client-fetch


# Python
pnpm dlx openapi-python-client generate --url openapi.json