# OpenAPI 端点文档该规范通过两遍生成：(1) 文件系统扫描器自动从处理程序工厂推断模式，(2) 合并脚本覆盖补充文件中人工编写的元数据。完整的人类可读指南位于“docs/OPENAPI_GUIDE.md”。 ## 快速入门 ### 新的应用程序路由器端点 1. 使用处理程序工厂创建 `src/app/api//route.ts` 2. 使用 `InputSchema` \+ `OutputSchema` 创建 `src/app/api//schema.ts` 3.创建`src/lib/openapi/endpoints//.ts`（补充） 4. 从 `src/lib/openapi/endpoints//index.ts` 导出补充 5. 运行“npx tsx 脚本/generate-openapi.ts” 6. 在 `http://localhost:3000/api-docs` 进行验证 ### 更新现有端点 1. 修改 `schema.ts` 中的模式 — 由扫描仪自动捕获 2. 更新 `src/lib/openapi/endpoints//` 中的补充元数据/示例 3. 运行“npx tsx 脚本/generate-openapi.ts” ### 新的边缘函数端点 1. 在 `src/lib/openapi/endpoints//edge-process-imports.ts` 中创建注册函数 2. 将 `registry.registerPath()` 与原始 `SchemaObject` （不是 Zod）一起使用 3. 从 `scripts/generate-openapi.ts` 导入并调用 4. 运行“npx tsx 脚本/generate-openapi.ts” 5. 在 `http://localhost:3000/api-docs` 进行验证有关边缘函数的详细信息，请参阅 [reference.md]()。 ## 新的应用程序路由器端点 ### 第 1 步：创建路由处理程序使用 src/lib/api-helpers/create-handler.ts 中的 4 个处理程序工厂之一： * `createGetApiHandlerWithAuth` — 带有身份验证的 GET * `createPostApiHandlerWithAuth` — 带有身份验证的 POST * `createGetApiHandler` — 无需身份验证的 GET * `createPostApiHandler` — 无需身份验证的 POST // src/app/api/<域>/<端点>/route.ts 从“@/lib/api-helpers/create-handler”导入{ createGetApiHandlerWithAuth }；从“./schema”导入{MyInputSchema，MyOutputSchema}； const ROUTE = "域端点名称"; 导出常量 GET = createGetApiHandlerWithAuth({ 路线：路线，输入架构：我的输入架构，输出架构：MyOutputSchema，处理程序：异步（{数据，supabase，用户，路线}）=> { // 业务逻辑返回 { 结果：“值” }; }, }); ### 第 2 步：创建架构文件将 Zod 模式并置到 `route.ts` 旁边： // src/app/api/<域>/<端点>/schema.ts 从“zod”导入{z}；导出 const MyInputSchema = z.object({ url: z.string(), }); 导出 const MyOutputSchema = z.object({ 结果：z.string(), }); ### 步骤 3：创建补充文件补充提供扫描仪无法推断的元数据：标签、摘要、描述、示例。 // src/lib/openapi/endpoints/<域>/<端点名称>.ts 从“@/lib/openapi/supplement-types”导入{ type EndpointSupplement }；从“@/lib/openapi/registry”导入 { bearerAuth } ；导出常量 myEndpointSupplement = { 路径：“/<域>/<端点名称>”，方法：“获取”，标签：[“<域>”]，摘要：“标量标题的简短描述”，描述：“端点功能的详细说明。”，安全性： [{ [bearerAuth.name]: [] }, {}], 响应示例：{ 数据：{结果：“值”}，错误：空， }, } 满足 EndpointSuplement； **规则：** * `path` 是相对于 `/api` 的（例如，`/bookmarks/check-url` 不是 `/api/bookmarks/check-url`） * `method` 为小写：`"get"` 或 `"post"` * 标签大写：`"Bookmarks"`、`"Categories"`、`"Twitter"` * 安全 `[{ [bearerAuth.name]: [] }, {}]` — 空 `{}` 表示也接受 cookie 身份验证 * 导出名称：`Suplement` ### 步骤 4：从桶中导出 // src/lib/openapi/endpoints/<域>/index.ts 从“./<端点名称>”导出 { myEndpointSupplement }； ### 步骤 5：重新生成并验证 npx tsx 脚本/generate-openapi.ts 打开“http://localhost:3000/api-docs”并验证端点是否出现。 ## 更新现有端点 ### 架构更改修改 `schema.ts` 中的 Zod 架构 - 扫描器会自动拾取它。 GitHub Actions 变更日志工作流程在每次推送到“dev”时运行“oasdiff”，并将更改附加到“docs/API_CHANGELOG.md”。 ### 更新补充元数据直接编辑补充文件：`summary`、`description`、`tags`、`additionalResponses`。 ### 添加示例 **单个示例**（简单端点）：响应示例：{ 数据：{ id：1，名称：“示例”}，错误：空， }, **命名示例**（多个场景 - 在标量中创建一个下拉菜单）：响应示例：{ “幸福之路”：{ 摘要：“响应成功”， description: "返回创建的资源。", 值：{数据：{id：1}，错误：null}， }, “检测到重复”：{ 摘要：“跳过重复”，描述: "URL 已添加书签。", 值：{ 数据：{ 插入：0，跳过：1 }，错误：null }， }, }, **400 错误示例：** 响应400示例：{ “空数组”：{ 摘要：“空书签数组”，描述：“当书签数组没有元素时失败。”， value: { data: null, error: "书签: 数组必须包含至少 1 个元素" }, }, }, 附加响应：{ 400: { 描述: "无效的请求正文或书签数据" }, }, 当补充文件超过 250 行时，将示例提取到“-examples.ts”。 **参数示例**（标量中的 GET 查询参数下拉列表）：参数示例：{ 电子邮件：{ “有效用户”：{ 摘要：“有效的用户电子邮件”，描述：“返回此电子邮件的用户数据。”, 值：“user@example.com”， }, “未知电子邮件”：{ 摘要：“不存在的电子邮件”，描述：“返回 null/空结果。”，值：“nobody@example.com”， }, }, }, 外部键 = 参数名称（必须与生成的规范中的“名称”匹配）。内部映射 = 标准命名示例。在 Scalar 的“Try It”面板中为每个查询参数创建一个下拉列表。 ## 补充参考 ### EndpointSuplement 字段领域|类型 |目的 ---|---|--- `路径` | `字符串` |相对于`/api`的路由路径（必填） `方法` | `字符串` | `"get"` 或 `"post"` 小写（必填） `标签` | `字符串[]` |标量侧边栏分组 `总结` | `字符串` |短标题（一行） `描述` | `字符串` |详细解释（支持markdown） `安全` | `数组<记录<字符串，字符串[]>>` |授权要求 `请求示例` | `记录<字符串，未知>` |单个请求正文示例 `请求示例` |命名示例对象 |多个请求示例 `响应示例` | `记录<字符串，未知>` |单个 200 响应示例 `响应示例` |命名示例对象 |多个 200 响应示例 `response400 示例` | `记录<字符串，未知>` |单个 400 错误示例 `response400Examples` |命名示例对象 |多个 400 错误示例 `附加响应` | `记录<编号，{描述}>` |额外响应代码（400、403、404） `参数示例` | `记录<字符串，NamedExamples>` |每个参数命名示例（GET 下拉列表） ### 命名约定 * 导出名称：`Supplement`（例如，`checkUrlSupplement`） * 命名示例键：kebab-case (`"single-tweet"`, `"validation-error"`) * 示例文件：`<端点名称>-examples.ts`（例如，`sync-examples.ts`） * 标签：大写（`"Bookmarks"`、`"iPhone"`） * 所有命名示例都需要“摘要”和“描述” * 首先是快乐路径，然后是验证错误 ### 响应组件扫描器为每个端点注册 3 个“$ref”响应组件： * `ValidationError` (400) — `{ 数据：null，错误：字符串 }` * `未经授权` (401) — `{ 数据：null，错误：“未经过身份验证” }` * `InternalError` (500) — `{ data: null, error: "无法处理请求" }` `additionalResponses` 会覆盖 400 描述，同时保留架构。 ## 代理提示模板 ### 为新端点创建补充 > 我刚刚在 `src/app/api//route.ts` 创建了一个新的 App Router 端点，其架构位于 `src/app/api//schema.ts`。创建 OpenAPI 补充文件，将其从桶中导出，重新生成规范，并在“/api-docs”处进行验证。 > > 域名：`<书签|类别|标签|twitter|instagram|raindrop|个人资料|iphone>` ### 更新现有端点的示例 > 更新“”端点的 OpenAPI 示例。阅读 `src/lib/openapi/endpoints//.ts` 处的当前补充，为这些场景添加命名示例：[描述场景]。重新生成规范并验证。 ### 添加 400 个错误示例 > 将“response400Examples”添加到“<端点名称>”补充中。包括以下示例：[列出验证错误]。还要添加 `additionalResponses: { 400: { description: "<自定义描述>" } }`。重新生成并验证。 ### 添加 GET 端点的参数示例 > 将“parameterExamples”添加到每个查询参数的“”补充中。包括以下示例：[列出每个参数的测试场景]。重新生成规范并验证 Scalar 的“Try It”面板中是否显示下拉列表。 ### 记录一个新的边缘函数 > 我在 `supabase/functions//` 创建了一个新的 Supabase Edge Function。按照“src/lib/openapi/endpoints/instagram/edge-process-imports.ts”中的模式在 OpenAPI 规范中注册它。使用“serviceRoleAuth”、“edgeFunctionServers”和原始“SchemaObject”。将其连接到“scripts/generate-openapi.ts”。 ## 故障排除 ### 补充未出现在规范中 1. 补充是否从域的“index.ts”桶中导出？ 2. `path` 是否与路由路径完全匹配（相对于 `/api`，没有尾部斜杠）？ 3. `method` 是否与导出的处理程序匹配（`GET` 为 `"get"`，`POST` 为 `"post"`）？ 4. 检查控制台输出 - `mergeSupplements` 打印不匹配补充的警告 ### 400 个示例未显示 1. 补充是否有`additionalResponses: { 400: { description: "..." } }`？ 2. 命名示例是否使用“response400Examples”（而不是“responseExamples”）？ 3.合并脚本在提供示例时自动初始化400内容 ### 常见错误 * 使用 `/api/bookmarks/check-url` 而不是 `/bookmarks/check-url` 作为路径 * 忘记“-examples.ts”文件中示例数据对象的“as const” * 当您需要“responseExamples”（命名/复数）时，使用“responseExample”（单数） * 命名示例中缺少“摘要”或“描述”——两者都是必需的有关边缘函数模式和复杂示例，请参阅 [reference.md]()。

OpenAPI 端点

包含技能