停止手动编写 OpenAPI 规范

Source: Dev.to

手动编写 OpenAPI 规范的问题

编写 API 文档非常繁琐。构建完一个端点后，你常常要花几分钟去编写 YAML，而这些 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 定义。

关键特性

• Swagger UI 可通过 /docs 访问（包括身份验证支持）
• 能够过滤端点并隐藏内部路由，防止出现在公共文档中
• 零重复：单一模式同时用于验证和文档

安装

npm install codehooks-js@latest

入门指南

1. 在 app.crudlify() 之前调用 app.openapi()。
2. 使用 coho deploy 部署。
3. 在 /docs 访问你的实时文档。

不再需要手写 YAML。不再有文档漂移。只需编写代码。

进一步阅读

完整文档：