从现有路由生成 OpenAPI 规范

遍历 Express 或 Fastify 路由表，从处理函数与校验 schema 推断参数和响应类型，输出 OpenAPI 3.1 文档供客户端与文档使用。

规范应跟随代码

手工维护的 OpenAPI 文件总会与路由漂移。从路由表和已有校验 schema 生成规范，使规范只在代码变更时才变。

registry.registerPath({
  method: 'post',
  path: '/users',
  request: { body: z.object({ email: z.string().email() }) },
  responses: { 201: z.object({ id: z.string() }) },
});

对输出做 lint

生成的规范仍可能有悬空引用或非法 schema。在 CI 中运行 linter，任何错误都让构建失败。把未文档化路由也视为错误，新端点不能无 schema 上线。

npx @redocly/cli lint openapi.json

预期结果

openapi.json 覆盖每条路由，linter 零错误，文档站点每次构建从规范重新生成。前端工程师读规范而非追问端点是否存在。运行时逻辑决定的状态码需手工补充描述。