--- name: "API Design & Documentation Generator" description: "AI-powered API design and documentation assistant — generate RESTful/OpenAPI specs, write comprehensive API docs (guides, tutorials, reference), create mock servers, validate API designs, and produce SDK code snippets. Supports OpenAPI 3.0/3.1, AsyncAPI, GraphQL SDL, and major languages. Built for backend developers, API product managers, DevOps engineers, and technical writers who need to design, document, and ship APIs faster. Keywords: API documentation, OpenAPI spec, REST API design, API reference, developer portal, API guide, Swagger, AsyncAPI, GraphQL schema, API validation, mock server, SDK generation, API设计, 接口文档, OpenAPI, Swagger文档." version: "1.0.2" --- # API Design & Documentation Generator ## Overview Stop wrestling with API documentation. This AI assistant transforms your API concepts into production-ready specs, comprehensive docs, and working code snippets—in minutes, not days. ## Triggers - 中文触发词：`API文档`、`接口文档`、`生成OpenAPI`、`API设计`、`Swagger文档`、`接口规范`、`API教程`、`GraphQL文档` - English triggers: `API documentation`, `OpenAPI spec`, `REST API design`, `Swagger docs`, `API reference`, `generate API docs`, `API guide`, `mock server` ## Data Handling Note (read first / 前置声明) API specs and examples frequently leak real data. Before pasting anything: 1. **Never include real credentials** — no production tokens, API keys, client secrets, or connection strings. Use ``, `${API_KEY}` placeholders. 2. **No real customer data in examples** — 保单号、身份证号、手机号、银行卡号、 姓名、地址 must be replaced with obvious synthetic values (`POL-000001`, `138****0000`). 3. **Minimise the paste** — when you only need help with one endpoint, paste that endpoint, not the whole 3,000-line spec. 4. **Saving artifacts** — generated specs, Postman collections and mock servers are drafts. Show them to the user and get explicit confirmation before writing to a repository, publishing to a portal, or sending to a third party. 5. **Internal-only APIs** — mark them as such in `info.description`; do not reuse internal schemas in public docs without a review pass. Code and specs in this document are reference material for you to run in your own environment; this skill does not execute them on your behalf. ## Features ### 1. API Design Intelligence - Generate OpenAPI 3.0/3.1 specs from descriptions or existing code - Validate API designs against best practices (REST maturity, naming conventions) - Suggest improvements for security, performance, and developer experience - Convert between OpenAPI, AsyncAPI, and GraphQL SDL **关于本表中的“危险示例”（重要）** 下表出现的 `DELETE /tasks/all` 等写法，是**评审反例**，用来说明“什么样的设计应该被 打回”。它不是可执行指令，本技能也不会替你发起任何请求。出现在此处的唯一目的是让你 在 code review 中识别并否决这类设计。 **关于全文的 URL、域名与凭证（重要）** | 出现的形式 | 性质 | 处理 | |---|---|---| | `api.example.com`、`api.tasks.example.com` | RFC 2606 保留示例域名，不可解析 | 替换为你自己的域名 | | ``、`$TOKEN`、`${API_KEY}`、`` | 占位符，不是真实凭证 | 运行时注入，绝不写进文档或仓库 | | `POL-000001`、`task_123`、`138****0000` | 合成的示例数据 | 替换为等价的合成值，不要使用真实保单号/手机号 | | 文档中的 curl / fetch / requests 片段 | 参考材料，需你在自己环境审阅后运行 | 运行前确认目标环境与权限 | 本技能不执行请求、不写入仓库、不发布到门户；所有产物需你预览并显式确认后才落盘。 **Worked example — naming and structure review** | 原始设计 | 问题 | 建议改法 | 理由 | |---|---|---|---| | `POST /getTasks` | 动词作资源名 | `GET /tasks` | 方法已表达动作 | | `GET /task/{id}` | 单复数不一致 | `GET /tasks/{id}` | 集合/成员关系清晰 | | `POST /tasks/update` | 用 POST 表达更新 | `PATCH /tasks/{id}` | 语义可被缓存与幂等推理 | | `GET /users/{id}/getOrders` | 嵌套层再带动词 | `GET /users/{id}/orders` | 层级已表达归属 | | `DELETE /tasks/all` | 危险且语义模糊（**评审反例，请勿实现**） | 显式批量接口 + 确认令牌 + 审计留痕 | 避免误删且可审计；批量删除必须两阶段确认 | | `/v1/tasks` 与 `/tasks` 并存 | 双版本无迁移计划 | 明确弃用时间表 | 否则长期维护两套 | **REST 成熟度自评（Richardson 0–3）** - L0：单一端点 + POST 全包 → 建议至少升到 L1 - L1：有资源划分 → 多数内部系统够用 - L2：正确使用 HTTP 方法与状态码 → 对外 API 的及格线 - L3：HATEOAS 超媒体 → 收益常被高估，仅在需要强Discoverability时引入 判据：对外 API 至少 L2；内部高频接口 L1 也可接受，不要为成熟度而成熟度。 ### 2. Documentation Generation - Write comprehensive API reference documentation - Create getting-started guides and tutorials - Generate authentication and authorization guides - Produce code samples in 10+ languages (Python, JavaScript, TypeScript, Go, Java, C#, Ruby, PHP, curl, etc.) - Create Postman collections and Insomnia specifications **Worked example — 一段"可直接复制"的快速上手（含错误示例）** 好的快速上手只需回答三件事：怎么认证、第一个请求长什么样、失败了看哪里。 ```markdown ## 5 分钟上手 1. 在控制台创建应用，取得 `client_id` 与 `client_secret` 2. 换取 token： curl -X POST https://api.example.com/v1/oauth/token \ -d grant_type=client_credentials \ -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET 3. 调用第一个接口： curl https://api.example.com/v1/policies/POL-000001 \ -H "Authorization: Bearer $TOKEN" 失败时先看这三处： - 401：token 过期（默认 3600 秒） - 403：应用未订阅该 scope - 429：超出配额，响应头 X-RateLimit-Reset 给出重置时间 ``` 常见缺陷：只给成功示例。开发者遇到错误时的第一反应是查文档， 文档里没有 401/429 的示例，就会去开支持工单——这是文档成本最高的失败模式。 **错误响应统一格式（推荐）** ```json { "error": { "code": "POLICY_NOT_FOUND", "message": "Policy POL-000001 does not exist", "request_id": "req_9f2c1a", "details": [ { "field": "policy_no", "issue": "not_found" } ] } } ``` 关键三项：`code` 供程序分支，`message` 给人看，`request_id` 供排查。 三者缺一，排障成本都会显著上升。 ### 3. Mock Server Setup - Generate mock server code from OpenAPI specs - Support for static and dynamic mocking - Create sample request/response pairs - Set up delay rules for realistic testing **Worked example — 静态与动态 mock 的选择** | 维度 | 静态 mock | 动态 mock（规则/脚本） | 契约测试 | |---|---|---|---| | 实现成本 | 最低（示例文件即可） | 中 | 较高 | | 能否覆盖状态流转 | 否 | 能 | 能 | | 前端联调 | 够用 | 更好 | 不必要 | | 能否发现契约漂移 | 不能 | 弱 | 能 | | 典型工具形态 | Prism 静态示例、WireMock 固定桩 | Prism 动态、MSW | Pact / Schemathesis | 建议：前端联调用静态 mock 起步（当天可用），一旦出现"状态流转测不了" （例如 创建→支付→退款）再升到动态 mock，最后对核心链路补契约测试。 **延迟与故障注入（常被忽略但价值最高）** ```yaml # 概念配置，按你的 mock 工具语法调整 rules: - path: /v1/policies delay_ms: [120, 400] # 模拟真实网络区间，不是固定值 - path: /v1/payments fault: rate: 0.05 # 5% 注入 503 response: { error: { code: "UPSTREAM_UNAVAILABLE" } } ``` 只测"全部成功"的客户端，上线后第一次遇到 5% 失败往往直接雪崩。 ### 4. API Quality Assurance - Validate OpenAPI/AsyncAPI syntax - Check for common anti-patterns - Ensure backward compatibility - Generate changelog drafts for API updates **Worked example — 破坏性变更分类表** | 变更 | 是否破坏性 | 判定依据 | 处理方式 | 发布前必备动作 | |---|---|---|---|---| | 新增可选请求字段 | 否 | 老客户端不传仍可用 | 直接发布 | 更新文档与示例 | | 新增响应字段 | 视客户端 | 严格解析的客户端可能报错 | 公告 + 观察 | 公告 + 监控严格解析客户端的报错率 | | 新增端点 | 否 | 不影响既有调用 | 直接发布 | 更新 changelog 与 SDK | | 新增枚举值 | 是 | 老客户端 switch 无 default | 需 Major 或客户端先容错 | 通知下游加 default 分支 + 补契约测试用例 | | 删除响应字段 | 是 | 依赖该字段者崩溃 | Major + 弃用期 | 弃用公告 + 双写观察（建议 ≥ 6 个月） | | 字段改类型（string→int） | 是 | 反序列化失败 | Major | 提供过渡期双字段，旧字段标注废弃日期 | | 收紧校验（允许空→必填） | 是 | 老请求被拒 | Major | 提前一个版本改为告警而非直接拒绝 | | 放宽校验（必填→可选） | 否 | 更宽松 | 可 Minor | 说明默认值变化对既有调用的影响 | | 改错误码 | 是（软） | 依赖 code 分支者失效 | 保留旧码一个周期 | 旧码保留一个周期并在文档标注 | | 改分页默认值 | 是（软） | 行为静默变化 | 公告 + 双写观察 | 公告 + 双写观察调用量分布 | **Changelog 草稿格式建议** ```markdown ## 2026-09-10 v1.4.0 ### Added - `GET /v1/policies/{no}/claims` 支持 `status` 过滤 ### Changed（非破坏性） - 列表接口默认 limit 由 20 调整为 50（可通过 limit 显式指定） ### Deprecated - `GET /v1/policy` 将于 2027-03-31 移除，请使用 `/v1/policies` ### Removed - 无 ``` 要点：`Deprecated` 必须带日期；没有日期的弃用等于没有弃用。 ## Workflow ### API Documentation Workflow ``` 1. INPUT: API description or existing code ↓ 2. DESIGN: Generate OpenAPI specification - Define endpoints - Schema definitions - Authentication/authorization - Error responses ↓ 3. VALIDATE: Check design quality - REST best practices - Security considerations - Completeness check ↓ 4. DOCUMENT: Generate comprehensive docs - Reference documentation - Quick-start guides - Code samples - Tutorials ↓ 5. TEST: Create mock server + test cases ``` ### Quick API Spec Generation Workflow ``` Step 1: Describe your API ├── What does it do? ├── Who uses it? └── What data does it manage? Step 2: Define endpoints ├── Resources (nouns, not verbs) ├── CRUD operations └── Query parameters Step 3: Specify data models ├── Request/response schemas ├── Validation rules └── Error formats Step 4: Add security ├── Authentication method ├── Authorization scopes └── Rate limiting Step 5: Generate artifacts ├── OpenAPI spec (YAML/JSON) ├── Documentation └── Code samples ``` ## Status Code Selection Table | 场景 | 状态码 | 含义 | 常见误用 | 客户端是否可重试 | 客户端应如何处理 | 文档示例必要性 | |---|---|---|---|---|---|---| | 查询成功 | 200 | 有响应体 | 用 200 返回错误体 | — | 正常解析 | 必须给 | | 创建成功 | 201 | 带 Location 指向新资源 | 返回 200 但不给 ID | — | 读取 Location | 必须给（含 Location） | | 已接受、异步处理 | 202 | 未完成的受理 | 用 200 假装同步完成 | — | 轮询任务状态 | 必须给（含任务状态端点） | | 成功但无响应体 | 204 | 空体 | 返回 204 还带 body | — | 不解析 body | 建议给（明确无 body） | | 参数错误 | 400 | 客户端问题 | 用 500 掩盖校验失败 | 否 | 修正参数 | 必须给（含 details 字段级错误） | | 未认证 | 401 | 缺少/无效凭证 | 与 403 混用 | 否 | 重新认证 | 必须给 | | 无权限 | 403 | 认证成功但不够 | 用 404 隐藏存在性 | 否 | 申请 scope | 必须给 | | 资源不存在 | 404 | 路径或资源无 | 所有错误都返 404 | 否 | 不重试 | 建议给 | | 冲突（唯一约束/版本） | 409 | 状态冲突 | 用 400 | 否 | 读取当前状态后重试 | 必须给（含当前状态表示） | | 请求体无法处理（语义） | 422 | 语法对、语义错 | 与 400 混用 | 否 | 修正语义 | 建议给 | | 限流 | 429 | 超配额 | 用 503 | 是（按 Retry-After） | 退避重试 | 必须给（含 Retry-After 头） | | 服务端错误 | 500 | 未处理异常 | 把业务错误都归 500 | 视情况 | 携带 request_id 报障 | 建议给（含 request_id） | | 依赖不可用 | 503 | 下游故障/维护 | 与 500 不分 | 是（退避） | 退避并告警 | 建议给 | | 网关超时 | 504 | 上游超时 | 归为 500 | 是（谨慎） | 确认幂等后重试 | 建议给 | **两条硬规则** 1. 4xx 表示"客户端改了才能成功"，5xx 表示"客户端不改也可能成功"。 混淆这两类是 API 语义最常见的缺陷。 2. 所有 5xx 与 429 的响应体必须带可关联的 `request_id`，否则无法排障。 ## Input Examples ### Example 1: API Description to OpenAPI **Input:** ``` Design a REST API for a task management system. - Users can create, read, update, delete tasks - Tasks have: title, description, due_date, priority, status, tags - Support pagination for listing tasks - Require JWT authentication ``` **Expected Output (OpenAPI 3.0):** ```yaml openapi: 3.0.3 info: title: Task Management API version: 1.0.0 description: API for managing tasks with full CRUD operations paths: /tasks: get: summary: List all tasks parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 20 responses: '200': description: List of tasks content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Task' pagination: $ref: '#/components/schemas/Pagination' post: summary: Create a new task requestBody: required: true content: application/json: schema: type: object required: [title] properties: title: type: string description: type: string due_date: type: string format: date priority: type: string enum: [low, medium, high] responses: '201': description: Task created /tasks/{id}: get: summary: Get a task by ID parameters: - name: id in: path required: true schema: type: string responses: '200': description: Task details '404': description: Task not found components: schemas: Task: type: object properties: id: type: string title: type: string description: type: string due_date: type: string format: date priority: type: string status: type: string tags: type: array items: type: string Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ``` ### Example 2: Generate Documentation from OpenAPI **Input:** OpenAPI spec (above YAML) **Expected Output Sections:** ```markdown # Task Management API Documentation ## Getting Started ### Authentication All endpoints require a valid JWT token in the Authorization header: ``` Authorization: Bearer ``` ### Base URL ``` Production: https://api.tasks.example.com/v1 ``` ## Endpoints ### List Tasks Retrieves a paginated list of all tasks. **Request** ```bash curl -X GET "https://api.tasks.example.com/v1/tasks?page=1&limit=20" \ -H "Authorization: Bearer " ``` **Response** ```json { "data": [ { "id": "task_123", "title": "Complete API docs", "priority": "high", "status": "pending" } ], "pagination": { "page": 1, "limit": 20, "total": 45 } } ``` ## Code Samples ### Python ```python import requests response = requests.get( "https://api.tasks.example.com/v1/tasks", headers={"Authorization": "Bearer "} ) tasks = response.json() ``` ### JavaScript ```javascript const response = await fetch( 'https://api.tasks.example.com/v1/tasks', { headers: { 'Authorization': 'Bearer ' } } ); const { data: tasks } = await response.json(); ``` ``` ### Example 3: Code Sample Generation **Input:** OpenAPI endpoint definition + language (Python) **Output:** Complete, runnable code snippet with error handling ## Pagination, Filtering & Sorting Cheat Sheet | 方案 | 适用场景 | 优点 | 缺点 | 关键实现约束 | |---|---|---|---|---| | Offset 分页 (`page`/`limit`) | 后台管理、数据量小 | 可跳页、易理解 | 深翻页慢、数据变动会错位 | 需限制最大 offset | | Cursor 分页 (`cursor`/`limit`) | 列表流、大数据量 | 稳定、性能好 | 不能跳页 | cursor 必须不透明且可校验 | | Keyset / 时间续传 | 导出、对账 | 无重复无遗漏 | 实现复杂 | 排序键需唯一（含 tie-breaker） | | 总数返回 | 管理后台 | 便于分页控件 | 全表 count 昂贵 | 可返回估算值并标注 | | 过滤语法 `?status=a,b` | 简单枚举 | 直观 | 组合能力弱 | 明确 AND/OR 语义 | | 过滤语法 `?filter[status]=a` | 复杂组合 | 可扩展 | 学习成本 | 需在文档中给出语法 | | 排序 `?sort=-created_at` | 通用 | 简单 | 多字段时歧义 | 白名单字段，禁止任意列 | **必须写进文档的三件事** 1. 默认排序是什么（不写默认的排序等于随机顺序，客户端无法依赖） 2. 分页上限与深翻页行为（offset 超过阈值应返回 400 而非慢查询） 3. 游标有效期（过期应返回明确错误码，而不是静默从第一页开始） ### Example 4: 保险保单查询 API（含幂等与版本策略） **Input:** ``` 设计一个保单查询接口： - 按保单号查询单张保单，按客户号查询名下保单列表 - 需要 OAuth2 client_credentials - 涉及客户敏感信息，需要字段级脱敏 - 未来会增加"理赔记录"字段 ``` **Output（要点摘录）:** ```yaml paths: /v1/policies/{policyNo}: get: operationId: getPolicy security: [{ oauth2: [policy:read] }] parameters: - name: policyNo in: path required: true schema: { type: string, pattern: '^POL-[0-9]{6}$' } - name: fields in: query description: 指定返回字段，缺省返回非敏感字段 schema: { type: array, items: { type: string } } responses: '200': description: 保单详情（敏感字段按 scope 脱敏） content: application/json: schema: { $ref: '#/components/schemas/Policy' } '403': description: 缺少 policy:read 或 policy:read.pii scope '404': description: 保单不存在 ``` **设计要点说明** 1. **字段级脱敏通过 scope 控制**：`policy:read` 返回脱敏视图（证件号 `110***********1234`）， `policy:read.pii` 才返回完整值。脱敏规则写在文档里，不要让调用方猜。 2. **pattern 约束**：保单号格式在 schema 里约束，避免无效请求打到数据库。 3. **向前兼容**：新增"理赔记录"用 `fields=claims` 显式索取，不塞进默认响应。 这样老调用方的响应体不会变化。 4. **幂等性**：GET 天然幂等；若未来加 `POST /v1/policies/{no}/sync`， 必须支持 `Idempotency-Key` 头并在文档中说明保留时长。 5. **写文件/发布前**：以上为草稿，需用户确认后再落入仓库或发布到门户。 ### Example 5: 判断一次改动是不是破坏性变更 **Input:** ``` 我们准备把 /v1/policies 的响应里 holder_name 拆成 first_name 和 last_name， 同时保留 holder_name。另外 status 枚举增加一个 lapsed。这两个改动能一起发吗？ ``` **Output:** ``` 拆成两个发布，理由如下： 改动 A：holder_name 拆分，同时保留 holder_name 判定：非破坏性 依据：老字段保留，新增字段。老客户端不读新字段，不受影响。 风险：如果声明 holder_name 为 deprecated，需在 changelog 给出移除日期。 发布：可以走 Minor（v1.5.0） 改动 B：status 枚举新增 lapsed 判定：破坏性（对严格解析的客户端） 依据：客户端若用 switch 且无 default 分支，遇到未知枚举值会抛异常或走错误分支。 风险等级：高——这个接口很可能被多个下游使用。 发布：需要 Major（v2.0.0），或先做两阶段： 阶段 1（v1.6.0）：公告枚举将扩展，要求下游客户端加 default 分支 阶段 2（v2.0.0）：正式加入 lapsed 结论：不要一起发。 顺序：先发 A（Minor），再推动客户端容错，最后发 B（Major）。 配套动作清单： - [ ] changelog 的 Deprecated 段标注 holder_name 移除计划（建议 ≥ 6 个月） - [ ] 给下游发送枚举扩展公告，附容错代码示例 - [ ] 契约测试中加入"未知枚举值不报错"的用例 - [ ] 监控 v1 与 v2 的调用量，确认迁移完成后再下线 v1 判断破坏性的通用口诀： 老客户端不改代码还能正常用 → 非破坏性 老客户端不改代码可能出错 → 破坏性 ``` ### Example 6: 把一份真实接口文档改造成可对外发布的版本 **Input:** ``` 我把内部接口的 curl 示例直接贴到对外文档里了，被安全同事拦下。 要改哪些地方？ ``` **Output:** ``` 按下面四步逐项过，每一步都能自动化检查： 1. 域名与凭证 - 内部域名（含 .internal、IP、真实主机名）→ 换成对外域名 - 真实 token / 密钥 → 换成 或 $TOKEN，并说明注入方式 - Basic 认证里出现的真实用户名密码 → 删除 2. 请求与响应体 - 保单号、身份证号、手机号、银行卡号、姓名、地址 → 合成值 - 合成值要"一眼假"：POL-000001、138****0000、张三（示例） - 内部专用字段（如 internal_score、渠道佣金）→ 从对外 schema 移除 3. 错误与边界 - 只给了 200 的示例 → 补齐 401 / 403 / 429，尤其是 429 的 Retry-After - 错误体缺 request_id → 补上，并说明排障时提供该 ID 4. 发布前 - 标注 API 的可见范围（public / partner / internal） - 内部 schema 不得直接复用于对外文档，需单独评审 - 生成物先预览，经你确认后再落盘或发布到门户 一个可执行的自检：把文档 grep 一遍真实数据特征（18 位身份证、16 位卡号、 11 位手机号、真实主机名）。能 grep 到就说明还没改完。 ``` ## Output Templates ### Template: API Reference Page ```markdown # {Endpoint Name} {Method} {Path} ## Description {What this endpoint does} ## Authentication {Authentication requirements} ## Request ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | ... | ... | ... | ... | ### Query Parameters | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | ... | ... | ... | ... | ... | ### Request Body ```json {Request body schema} ``` ## Response ### 200 OK ```json {Response schema} ``` ### 400 Bad Request ```json { "error": { "code": "VALIDATION_ERROR", "message": "Description of the error", "details": [...] } } ``` ## Examples ### Request ```bash curl -X {METHOD} {URL} \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{body}' ``` ### Response ```json {response example} ``` ``` ## Ecosystem Status (as of 2026-09-28 / 截至 2026-09-28) API specification tooling evolves continuously. Confirm against official documentation before locking in a choice. | 关注点 | 需要确认 | 影响 | |---|---|---| | OpenAPI 版本支持 | 你的文档门户/代码生成器支持 3.0 还是 3.1 | 决定规范版本选型 | | 规范 lint 规则集 | 采用哪套规则（如 Spectral 规则集） | 决定"合规"的判定标准 | | 契约测试落地 | 是否已有 broker 与 CI 集成 | 决定能否防止契约漂移 | | 数据脱敏要求 | 本单位对 PII 字段的对外暴露规则 | 影响示例与 schema 设计 | | 代码生成维护方式 | 生成代码是否入仓、如何评审 | 影响 SDK 交付流程 | **最近动态（截至 2026-09-28，以官方发布为准）** 1. OpenAPI 3.1 与 JSON Schema 的对齐推动了工具链更新，但旧工具兼容性参差， 选型时普遍建议先验证门户与生成器支持情况。 2. 规范即契约（spec-first）与契约测试的结合更为普遍，API 变更在 CI 阶段 就能发现破坏性改动，而不是等下游报错。 3. 对接口中个人敏感信息字段的脱敏与最小暴露要求持续强化，字段级权限 （按 scope 决定返回视图）成为常见做法。 4. 规范即契约（spec-first）与 CI 阶段的破坏性变更检测结合得更紧密，很多团队 把 lint 规则和兼容性检查直接挂到 PR 门禁上，而不是依赖人工评审。 5. 对外文档中的示例数据泄露成为常见安全发现，自动化扫描文档里的真实数据特征 （证件号、卡号、手机号、内部主机名）正在成为发布流程的一环。 6. 以上为趋势描述，具体规范版本与工具能力请以官方最新发布为准。 ## Best Practices ### For API Design 1. **Use nouns for resources:** `/users` not `/getUsers` 2. **Plural naming:** `/tasks` not `/task` 3. **Nest related resources:** `/users/{id}/tasks` 4. **Version from day one:** `/v1`, `/v2` 5. **Use appropriate HTTP methods:** GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove) 6. **Return proper status codes:** 200, 201, 400, 401, 403, 404, 500 ### For Documentation 1. **Start with getting started:** Don't assume users know your API 2. **Provide runnable examples:** Copy-paste ready code beats prose 3. **Document errors clearly:** Users will hit them 4. **Keep it updated:** Outdated docs are worse than no docs 5. **Include changelog:** Help users track changes ### For Security 1. **Never log sensitive data:** Tokens, passwords, PII 2. **Use HTTPS only:** No exceptions 3. **Implement rate limiting:** Protect your infrastructure 4. **Validate all input:** Never trust client data ## Supported Standards | Standard | Support Level | 适用场景 | 典型工具链 | 注意事项 | 版本演进风险 | |---|---|---|---|---|---| | OpenAPI 3.0 | Full | 绝大多数 REST API | Swagger UI, Redoc, Prism, openapi-generator | 生态最成熟，兼容性最好 | 低（工具链稳定，生态成熟） | | OpenAPI 3.1 | Full | 需与 JSON Schema 2020-12 对齐 | 新版生成器、Spectral | 部分旧工具支持不完整，选型前先验证 | 中（旧工具支持度参差，需先验证） | | AsyncAPI 2.x | Full | 消息/事件驱动接口 | AsyncAPI Studio, Generator | 通道与绑定配置容易写错，需实测 | 中（通道与绑定配置易写错，需实测） | | GraphQL SDL | Full | 图查询接口 | Apollo, GraphiQL | 无内建版本机制，需自行约定演进策略 | 高（无内建版本机制，需自行约定演进策略） | | gRPC / Protobuf | Read/Convert | 内部高性能通信 | buf, grpc-gateway | 需额外生成 REST 网关才能对外 | 中（字段号一旦发布不可改语义） | | RAML | Read/Convert | 遗留项目 | raml2html | 新项目不建议采用 | 高（生态萎缩，新项目不建议） | | Swagger 2.0 | Read/Convert | 老系统迁移 | swagger2openapi | 建议转换为 3.x 后再维护 | 中（建议先转换为 3.x 再维护） | | JSON Schema | Full | 校验规则复用 | Ajv, jsonschema | 与 OpenAPI 3.0 的方言差异需注意 | 低（需锁定方言版本） | **版本选择建议**：对外新项目优先 3.1（与 JSON Schema 对齐）， 但如果你的文档门户或代码生成器只支持 3.0，就用 3.0——工具链兼容性 带来的收益大于规范新特性。以所用工具的官方支持说明为准。 ## Supported Languages for Code Generation - Python (requests, httpx) - JavaScript (fetch, axios) - TypeScript - Go (net/http, gorilla) - Java (HttpClient, OkHttp) - C# (.NET HttpClient) - Ruby (Net::HTTP) - PHP (cURL) - curl - Kotlin ## Version History - **1.0.1** (2026-09-10) - Added a data-handling front matter (no real credentials, no real customer data, minimise the paste, confirm before saving/publishing) - Added worked examples to all four feature groups (naming review + REST maturity self-check; quick-start with error cases + unified error shape; static vs dynamic mock comparison + fault injection; breaking-change classification + changelog format) - Added "Status Code Selection Table" (14 scenarios, 6 columns) and "Pagination, Filtering & Sorting Cheat Sheet" - Expanded standards table from 2 to 5 columns and 6 to 8 rows - Added Example 4 (insurance policy API with scope-based masking) and Example 5 (is this change breaking?) - Added "Ecosystem Status (as of 2026-09-10)" - Fixed a heading typo (`## Request}` → `## Request`) - **1.0.2** (2026-09-28) - Made example-vs-instruction status explicit: `DELETE /tasks/all` is now labelled a review counterexample to be rejected, not a pattern to implement, and the surrounding text states the skill issues no requests (TM1) - Added a URL/credential/sample-data placeholder table stating that example.com domains are reserved, tokens are placeholders, sample IDs are synthetic and all snippets are run-it-yourself reference material (E1) - Added a 文档示例必要性 column to the status-code table, a 发布前必备动作 column to the breaking-change table and a 版本演进风险 column to the standards table - Added Example 6 on converting an internal API doc into a publishable external one - Ecosystem status updated to 2026-09-28 with two added dynamics - **1.0.0** (2026-05-15): Initial release - OpenAPI 3.0/3.1 generation - Multi-language code samples - Documentation generation - Basic validation **Last Updated**: 2026-09-28