{"id":"d7abecb8-0ec0-4984-8028-f3c9b2a9bda5","entityType":"agent","slug":"clawhub-gechengling-api-design-documentation","name":"API Design & Documentation Generator","canonicalUrl":"https://www.xpersona.co/agent/clawhub-gechengling-api-design-documentation","canonicalPath":"/agent/clawhub-gechengling-api-design-documentation","generatedAt":"2026-10-11T23:41:28.943Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":null},"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文档. Skill: API Design & Documentation Generator Owner: gechengling Summary: 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","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17ewqc4f2s6gpcbm88hy7fgvn85kg1g:api-design-documentation","sourceUrl":"https://clawhub.ai/gechengling/api-design-documentation","homepage":"https://clawhub.ai/gechengling/skills/api-design-documentation","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/gechengling/api-design-documentation","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/gechengling/skills/api-design-documentation","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"AI-powered API design and documentation assistant — generate RESTful/OpenAPI specs, write comprehensive API docs (guides, tutorials, reference), create mock ser"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":null},"stars":null,"forks":null,"downloads":1002,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.2","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T19:38:42.962Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T19:38:43.026Z","lastCrawledAt":"2026-10-11T19:38:42.962Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T19:38:42.962Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.2","createdAt":"2026-09-28T05:25:35.811Z","changelog":"明示DELETE /tasks/all为评审反例而非可执行指令（TM1）；新增URL/凭证/示例数据占位符性质对照表（E1）；状态码表新增示例必要性列、破坏性变更表新增发布前必备动作列、标准表新增版本演进风险列；新增Example 6对外文档脱敏改造；生态动态更新至2026-09-28","fileCount":3,"zipByteSize":15610},{"version":"1.0.1","createdAt":"2026-09-10T05:36:43.863Z","changelog":"1.0.1: 新增数据处理前置声明、四模块各补实例、状态码选用表(14场景6列)、分页过滤排序对照表、标准表扩至5列8行、示例4(保单API脱敏)-5(破坏性变更判定)、生态现状、修正标题typo","fileCount":3,"zipByteSize":13706},{"version":"1.0.0","createdAt":"2026-05-19T13:23:52.203Z","changelog":"Initial release of API Design & Documentation Generator. - Generate OpenAPI 3.0/3.1, AsyncAPI, and GraphQL SDL specs from descriptions or existing code - Automatically create comprehensive API documentation (reference, guides, tutorials) and code samples in multiple languages - Validate API designs for best practices, security, and compatibility - Produce mock servers and request/response examples for faster testing - Designed for backend developers, API product managers, DevOps engineers, and technical writers","fileCount":3,"zipByteSize":5405}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ewqc4f2s6gpcbm88hy7fgvn85kg1g:api-design-documentation","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T23:41:28.942Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gechengling-api-design-documentation/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":null},"readme":"Skill: API Design & Documentation Generator\n\nOwner: gechengling\n\nSummary: 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文档.\n\nTags: api-design-documentation:1.0.2, latest:1.0.2\n\nVersion history:\n\nv1.0.2 | 2026-09-28T05:25:35.811Z | user\n\n明示DELETE /tasks/all为评审反例而非可执行指令（TM1）；新增URL/凭证/示例数据占位符性质对照表（E1）；状态码表新增示例必要性列、破坏性变更表新增发布前必备动作列、标准表新增版本演进风险列；新增Example 6对外文档脱敏改造；生态动态更新至2026-09-28\n\nv1.0.1 | 2026-09-10T05:36:43.863Z | user\n\n1.0.1: 新增数据处理前置声明、四模块各补实例、状态码选用表(14场景6列)、分页过滤排序对照表、标准表扩至5列8行、示例4(保单API脱敏)-5(破坏性变更判定)、生态现状、修正标题typo\n\nv1.0.0 | 2026-05-19T13:23:52.203Z | auto\n\nInitial release of API Design & Documentation Generator.\n\n- Generate OpenAPI 3.0/3.1, AsyncAPI, and GraphQL SDL specs from descriptions or existing code\n- Automatically create comprehensive API documentation (reference, guides, tutorials) and code samples in multiple languages\n- Validate API designs for best practices, security, and compatibility\n- Produce mock servers and request/response examples for faster testing\n- Designed for backend developers, API product managers, DevOps engineers, and technical writers\n\nArchive index:\n\nArchive v1.0.2: 3 files, 15610 bytes\n\nFiles: skill-card.md (1780b), SKILL.md (32276b), _meta.json (143b)\n\nFile v1.0.2:SKILL.md\n\n---\r\nname: \"API Design & Documentation Generator\"\r\ndescription: \"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文档.\"\r\nversion: \"1.0.2\"\r\n---\r\n\r\n# API Design & Documentation Generator\r\n\r\n## Overview\r\n\r\nStop 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.\r\n\r\n## Triggers\r\n\r\n- 中文触发词：`API文档`、`接口文档`、`生成OpenAPI`、`API设计`、`Swagger文档`、`接口规范`、`API教程`、`GraphQL文档`\r\n- English triggers: `API documentation`, `OpenAPI spec`, `REST API design`, `Swagger docs`, `API reference`, `generate API docs`, `API guide`, `mock server`\r\n\r\n## Data Handling Note (read first / 前置声明)\r\n\r\nAPI specs and examples frequently leak real data. Before pasting anything:\r\n\r\n1. **Never include real credentials** — no production tokens, API keys, client\r\n secrets, or connection strings. Use ``, `${API_KEY}` placeholders.\r\n2. **No real customer data in examples** — 保单号、身份证号、手机号、银行卡号、\r\n 姓名、地址 must be replaced with obvious synthetic values (`POL-000001`,\r\n `138****0000`).\r\n3. **Minimise the paste** — when you only need help with one endpoint, paste that\r\n endpoint, not the whole 3,000-line spec.\r\n4. **Saving artifacts** — generated specs, Postman collections and mock servers\r\n are drafts. Show them to the user and get explicit confirmation before writing\r\n to a repository, publishing to a portal, or sending to a third party.\r\n5. **Internal-only APIs** — mark them as such in `info.description`; do not reuse\r\n internal schemas in public docs without a review pass.\r\n\r\nCode and specs in this document are reference material for you to run in your own\r\nenvironment; this skill does not execute them on your behalf.\r\n\r\n## Features\r\n\r\n### 1. API Design Intelligence\r\n- Generate OpenAPI 3.0/3.1 specs from descriptions or existing code\r\n- Validate API designs against best practices (REST maturity, naming conventions)\r\n- Suggest improvements for security, performance, and developer experience\r\n- Convert between OpenAPI, AsyncAPI, and GraphQL SDL\r\n\r\n\r\n**关于本表中的“危险示例”（重要）**\r\n\r\n下表出现的 `DELETE /tasks/all` 等写法，是**评审反例**，用来说明“什么样的设计应该被\r\n打回”。它不是可执行指令，本技能也不会替你发起任何请求。出现在此处的唯一目的是让你\r\n在 code review 中识别并否决这类设计。\r\n\r\n**关于全文的 URL、域名与凭证（重要）**\r\n\r\n| 出现的形式 | 性质 | 处理 |\r\n|---|---|---|\r\n| `api.example.com`、`api.tasks.example.com` | RFC 2606 保留示例域名，不可解析 | 替换为你自己的域名 |\r\n| ``、`$TOKEN`、`${API_KEY}`、`` | 占位符，不是真实凭证 | 运行时注入，绝不写进文档或仓库 |\r\n| `POL-000001`、`task_123`、`138****0000` | 合成的示例数据 | 替换为等价的合成值，不要使用真实保单号/手机号 |\r\n| 文档中的 curl / fetch / requests 片段 | 参考材料，需你在自己环境审阅后运行 | 运行前确认目标环境与权限 |\r\n\r\n本技能不执行请求、不写入仓库、不发布到门户；所有产物需你预览并显式确认后才落盘。\r\n\r\n\r\n\r\n**Worked example — naming and structure review**\r\n\r\n| 原始设计 | 问题 | 建议改法 | 理由 |\r\n|---|---|---|---|\r\n| `POST /getTasks` | 动词作资源名 | `GET /tasks` | 方法已表达动作 |\r\n| `GET /task/{id}` | 单复数不一致 | `GET /tasks/{id}` | 集合/成员关系清晰 |\r\n| `POST /tasks/update` | 用 POST 表达更新 | `PATCH /tasks/{id}` | 语义可被缓存与幂等推理 |\r\n| `GET /users/{id}/getOrders` | 嵌套层再带动词 | `GET /users/{id}/orders` | 层级已表达归属 |\r\n| `DELETE /tasks/all` | 危险且语义模糊（**评审反例，请勿实现**） | 显式批量接口 + 确认令牌 + 审计留痕 | 避免误删且可审计；批量删除必须两阶段确认 |\r\n| `/v1/tasks` 与 `/tasks` 并存 | 双版本无迁移计划 | 明确弃用时间表 | 否则长期维护两套 |\r\n\r\n**REST 成熟度自评（Richardson 0–3）**\r\n- L0：单一端点 + POST 全包 → 建议至少升到 L1\r\n- L1：有资源划分 → 多数内部系统够用\r\n- L2：正确使用 HTTP 方法与状态码 → 对外 API 的及格线\r\n- L3：HATEOAS 超媒体 → 收益常被高估，仅在需要强Discoverability时引入\r\n判据：对外 API 至少 L2；内部高频接口 L1 也可接受，不要为成熟度而成熟度。\r\n\r\n\r\n### 2. Documentation Generation\r\n- Write comprehensive API reference documentation\r\n- Create getting-started guides and tutorials\r\n- Generate authentication and authorization guides\r\n- Produce code samples in 10+ languages (Python, JavaScript, TypeScript, Go, Java, C#, Ruby, PHP, curl, etc.)\r\n- Create Postman collections and Insomnia specifications\r\n\r\n\r\n**Worked example — 一段\"可直接复制\"的快速上手（含错误示例）**\r\n\r\n好的快速上手只需回答三件事：怎么认证、第一个请求长什么样、失败了看哪里。\r\n\r\n```markdown\r\n## 5 分钟上手\r\n1. 在控制台创建应用，取得 `client_id` 与 `client_secret`\r\n2. 换取 token：\r\n curl -X POST https://api.example.com/v1/oauth/token \\\r\n -d grant_type=client_credentials \\\r\n -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET\r\n3. 调用第一个接口：\r\n curl https://api.example.com/v1/policies/POL-000001 \\\r\n -H \"Authorization: Bearer $TOKEN\"\r\n\r\n失败时先看这三处：\r\n- 401：token 过期（默认 3600 秒）\r\n- 403：应用未订阅该 scope\r\n- 429：超出配额，响应头 X-RateLimit-Reset 给出重置时间\r\n```\r\n\r\n常见缺陷：只给成功示例。开发者遇到错误时的第一反应是查文档，\r\n文档里没有 401/429 的示例，就会去开支持工单——这是文档成本最高的失败模式。\r\n\r\n**错误响应统一格式（推荐）**\r\n\r\n```json\r\n{\r\n \"error\": {\r\n \"code\": \"POLICY_NOT_FOUND\",\r\n \"message\": \"Policy POL-000001 does not exist\",\r\n \"request_id\": \"req_9f2c1a\",\r\n \"details\": [\r\n { \"field\": \"policy_no\", \"issue\": \"not_found\" }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n关键三项：`code` 供程序分支，`message` 给人看，`request_id` 供排查。\r\n三者缺一，排障成本都会显著上升。\r\n\r\n\r\n### 3. Mock Server Setup\r\n- Generate mock server code from OpenAPI specs\r\n- Support for static and dynamic mocking\r\n- Create sample request/response pairs\r\n- Set up delay rules for realistic testing\r\n\r\n\r\n**Worked example — 静态与动态 mock 的选择**\r\n\r\n| 维度 | 静态 mock | 动态 mock（规则/脚本） | 契约测试 |\r\n|---|---|---|---|\r\n| 实现成本 | 最低（示例文件即可） | 中 | 较高 |\r\n| 能否覆盖状态流转 | 否 | 能 | 能 |\r\n| 前端联调 | 够用 | 更好 | 不必要 |\r\n| 能否发现契约漂移 | 不能 | 弱 | 能 |\r\n| 典型工具形态 | Prism 静态示例、WireMock 固定桩 | Prism 动态、MSW | Pact / Schemathesis |\r\n\r\n建议：前端联调用静态 mock 起步（当天可用），一旦出现\"状态流转测不了\"\r\n（例如 创建→支付→退款）再升到动态 mock，最后对核心链路补契约测试。\r\n\r\n**延迟与故障注入（常被忽略但价值最高）**\r\n\r\n```yaml\r\n# 概念配置，按你的 mock 工具语法调整\r\nrules:\r\n - path: /v1/policies\r\n delay_ms: [120, 400] # 模拟真实网络区间，不是固定值\r\n - path: /v1/payments\r\n fault:\r\n rate: 0.05 # 5% 注入 503\r\n response: { error: { code: \"UPSTREAM_UNAVAILABLE\" } }\r\n```\r\n\r\n只测\"全部成功\"的客户端，上线后第一次遇到 5% 失败往往直接雪崩。\r\n\r\n\r\n### 4. API Quality Assurance\r\n- Validate OpenAPI/AsyncAPI syntax\r\n- Check for common anti-patterns\r\n- Ensure backward compatibility\r\n- Generate changelog drafts for API updates\r\n\r\n\r\n**Worked example — 破坏性变更分类表**\r\n\r\n| 变更 | 是否破坏性 | 判定依据 | 处理方式 | 发布前必备动作 |\r\n|---|---|---|---|---|\r\n| 新增可选请求字段 | 否 | 老客户端不传仍可用 | 直接发布 | 更新文档与示例 |\r\n| 新增响应字段 | 视客户端 | 严格解析的客户端可能报错 | 公告 + 观察 | 公告 + 监控严格解析客户端的报错率 |\r\n| 新增端点 | 否 | 不影响既有调用 | 直接发布 | 更新 changelog 与 SDK |\r\n| 新增枚举值 | 是 | 老客户端 switch 无 default | 需 Major 或客户端先容错 | 通知下游加 default 分支 + 补契约测试用例 |\r\n| 删除响应字段 | 是 | 依赖该字段者崩溃 | Major + 弃用期 | 弃用公告 + 双写观察（建议 ≥ 6 个月） |\r\n| 字段改类型（string→int） | 是 | 反序列化失败 | Major | 提供过渡期双字段，旧字段标注废弃日期 |\r\n| 收紧校验（允许空→必填） | 是 | 老请求被拒 | Major | 提前一个版本改为告警而非直接拒绝 |\r\n| 放宽校验（必填→可选） | 否 | 更宽松 | 可 Minor | 说明默认值变化对既有调用的影响 |\r\n| 改错误码 | 是（软） | 依赖 code 分支者失效 | 保留旧码一个周期 | 旧码保留一个周期并在文档标注 |\r\n| 改分页默认值 | 是（软） | 行为静默变化 | 公告 + 双写观察 | 公告 + 双写观察调用量分布 |\r\n\r\n**Changelog 草稿格式建议**\r\n\r\n```markdown\r\n## 2026-09-10 v1.4.0\r\n### Added\r\n- `GET /v1/policies/{no}/claims` 支持 `status` 过滤\r\n### Changed（非破坏性）\r\n- 列表接口默认 limit 由 20 调整为 50（可通过 limit 显式指定）\r\n### Deprecated\r\n- `GET /v1/policy` 将于 2027-03-31 移除，请使用 `/v1/policies`\r\n### Removed\r\n- 无\r\n```\r\n\r\n要点：`Deprecated` 必须带日期；没有日期的弃用等于没有弃用。\r\n\r\n\r\n## Workflow\r\n\r\n### API Documentation Workflow\r\n\r\n```\r\n1. INPUT: API description or existing code\r\n ↓\r\n2. DESIGN: Generate OpenAPI specification\r\n - Define endpoints\r\n - Schema definitions\r\n - Authentication/authorization\r\n - Error responses\r\n ↓\r\n3. VALIDATE: Check design quality\r\n - REST best practices\r\n - Security considerations\r\n - Completeness check\r\n ↓\r\n4. DOCUMENT: Generate comprehensive docs\r\n - Reference documentation\r\n - Quick-start guides\r\n - Code samples\r\n - Tutorials\r\n ↓\r\n5. TEST: Create mock server + test cases\r\n```\r\n\r\n### Quick API Spec Generation Workflow\r\n\r\n```\r\nStep 1: Describe your API\r\n├── What does it do?\r\n├── Who uses it?\r\n└── What data does it manage?\r\n\r\nStep 2: Define endpoints\r\n├── Resources (nouns, not verbs)\r\n├── CRUD operations\r\n└── Query parameters\r\n\r\nStep 3: Specify data models\r\n├── Request/response schemas\r\n├── Validation rules\r\n└── Error formats\r\n\r\nStep 4: Add security\r\n├── Authentication method\r\n├── Authorization scopes\r\n└── Rate limiting\r\n\r\nStep 5: Generate artifacts\r\n├── OpenAPI spec (YAML/JSON)\r\n├── Documentation\r\n└── Code samples\r\n```\r\n\r\n## Status Code Selection Table\r\n\r\n| 场景 | 状态码 | 含义 | 常见误用 | 客户端是否可重试 | 客户端应如何处理 | 文档示例必要性 |\r\n|---|---|---|---|---|---|---|\r\n| 查询成功 | 200 | 有响应体 | 用 200 返回错误体 | — | 正常解析 | 必须给 |\r\n| 创建成功 | 201 | 带 Location 指向新资源 | 返回 200 但不给 ID | — | 读取 Location | 必须给（含 Location） |\r\n| 已接受、异步处理 | 202 | 未完成的受理 | 用 200 假装同步完成 | — | 轮询任务状态 | 必须给（含任务状态端点） |\r\n| 成功但无响应体 | 204 | 空体 | 返回 204 还带 body | — | 不解析 body | 建议给（明确无 body） |\r\n| 参数错误 | 400 | 客户端问题 | 用 500 掩盖校验失败 | 否 | 修正参数 | 必须给（含 details 字段级错误） |\r\n| 未认证 | 401 | 缺少/无效凭证 | 与 403 混用 | 否 | 重新认证 | 必须给 |\r\n| 无权限 | 403 | 认证成功但不够 | 用 404 隐藏存在性 | 否 | 申请 scope | 必须给 |\r\n| 资源不存在 | 404 | 路径或资源无 | 所有错误都返 404 | 否 | 不重试 | 建议给 |\r\n| 冲突（唯一约束/版本） | 409 | 状态冲突 | 用 400 | 否 | 读取当前状态后重试 | 必须给（含当前状态表示） |\r\n| 请求体无法处理（语义） | 422 | 语法对、语义错 | 与 400 混用 | 否 | 修正语义 | 建议给 |\r\n| 限流 | 429 | 超配额 | 用 503 | 是（按 Retry-After） | 退避重试 | 必须给（含 Retry-After 头） |\r\n| 服务端错误 | 500 | 未处理异常 | 把业务错误都归 500 | 视情况 | 携带 request_id 报障 | 建议给（含 request_id） |\r\n| 依赖不可用 | 503 | 下游故障/维护 | 与 500 不分 | 是（退避） | 退避并告警 | 建议给 |\r\n| 网关超时 | 504 | 上游超时 | 归为 500 | 是（谨慎） | 确认幂等后重试 | 建议给 |\r\n\r\n**两条硬规则**\r\n1. 4xx 表示\"客户端改了才能成功\"，5xx 表示\"客户端不改也可能成功\"。\r\n 混淆这两类是 API 语义最常见的缺陷。\r\n2. 所有 5xx 与 429 的响应体必须带可关联的 `request_id`，否则无法排障。\r\n\r\n## Input Examples\r\n\r\n### Example 1: API Description to OpenAPI\r\n\r\n**Input:**\r\n```\r\nDesign a REST API for a task management system.\r\n- Users can create, read, update, delete tasks\r\n- Tasks have: title, description, due_date, priority, status, tags\r\n- Support pagination for listing tasks\r\n- Require JWT authentication\r\n```\r\n\r\n**Expected Output (OpenAPI 3.0):**\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: Task Management API\r\n version: 1.0.0\r\n description: API for managing tasks with full CRUD operations\r\n\r\npaths:\r\n /tasks:\r\n get:\r\n summary: List all tasks\r\n parameters:\r\n - name: page\r\n in: query\r\n schema:\r\n type: integer\r\n default: 1\r\n - name: limit\r\n in: query\r\n schema:\r\n type: integer\r\n default: 20\r\n responses:\r\n '200':\r\n description: List of tasks\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Task'\r\n pagination:\r\n $ref: '#/components/schemas/Pagination'\r\n post:\r\n summary: Create a new task\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n required: [title]\r\n properties:\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n enum: [low, medium, high]\r\n responses:\r\n '201':\r\n description: Task created\r\n\r\n /tasks/{id}:\r\n get:\r\n summary: Get a task by ID\r\n parameters:\r\n - name: id\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n responses:\r\n '200':\r\n description: Task details\r\n '404':\r\n description: Task not found\r\n\r\ncomponents:\r\n schemas:\r\n Task:\r\n type: object\r\n properties:\r\n id:\r\n type: string\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n status:\r\n type: string\r\n tags:\r\n type: array\r\n items:\r\n type: string\r\n Pagination:\r\n type: object\r\n properties:\r\n page:\r\n type: integer\r\n limit:\r\n type: integer\r\n total:\r\n type: integer\r\n securitySchemes:\r\n BearerAuth:\r\n type: http\r\n scheme: bearer\r\n bearerFormat: JWT\r\n```\r\n\r\n### Example 2: Generate Documentation from OpenAPI\r\n\r\n**Input:** OpenAPI spec (above YAML)\r\n\r\n**Expected Output Sections:**\r\n```markdown\r\n# Task Management API Documentation\r\n\r\n## Getting Started\r\n\r\n### Authentication\r\nAll endpoints require a valid JWT token in the Authorization header:\r\n```\r\nAuthorization: Bearer \r\n```\r\n\r\n### Base URL\r\n```\r\nProduction: https://api.tasks.example.com/v1\r\n```\r\n\r\n## Endpoints\r\n\r\n### List Tasks\r\nRetrieves a paginated list of all tasks.\r\n\r\n**Request**\r\n```bash\r\ncurl -X GET \"https://api.tasks.example.com/v1/tasks?page=1&limit=20\" \\\r\n -H \"Authorization: Bearer \"\r\n```\r\n\r\n**Response**\r\n```json\r\n{\r\n \"data\": [\r\n {\r\n \"id\": \"task_123\",\r\n \"title\": \"Complete API docs\",\r\n \"priority\": \"high\",\r\n \"status\": \"pending\"\r\n }\r\n ],\r\n \"pagination\": {\r\n \"page\": 1,\r\n \"limit\": 20,\r\n \"total\": 45\r\n }\r\n}\r\n```\r\n\r\n## Code Samples\r\n\r\n### Python\r\n```python\r\nimport requests\r\n\r\nresponse = requests.get(\r\n \"https://api.tasks.example.com/v1/tasks\",\r\n headers={\"Authorization\": \"Bearer \"}\r\n)\r\ntasks = response.json()\r\n```\r\n\r\n### JavaScript\r\n```javascript\r\nconst response = await fetch(\r\n 'https://api.tasks.example.com/v1/tasks',\r\n {\r\n headers: { 'Authorization': 'Bearer ' }\r\n }\r\n);\r\nconst { data: tasks } = await response.json();\r\n```\r\n```\r\n\r\n### Example 3: Code Sample Generation\r\n\r\n**Input:** OpenAPI endpoint definition + language (Python)\r\n\r\n**Output:** Complete, runnable code snippet with error handling\r\n\r\n## Pagination, Filtering & Sorting Cheat Sheet\r\n\r\n| 方案 | 适用场景 | 优点 | 缺点 | 关键实现约束 |\r\n|---|---|---|---|---|\r\n| Offset 分页 (`page`/`limit`) | 后台管理、数据量小 | 可跳页、易理解 | 深翻页慢、数据变动会错位 | 需限制最大 offset |\r\n| Cursor 分页 (`cursor`/`limit`) | 列表流、大数据量 | 稳定、性能好 | 不能跳页 | cursor 必须不透明且可校验 |\r\n| Keyset / 时间续传 | 导出、对账 | 无重复无遗漏 | 实现复杂 | 排序键需唯一（含 tie-breaker） |\r\n| 总数返回 | 管理后台 | 便于分页控件 | 全表 count 昂贵 | 可返回估算值并标注 |\r\n| 过滤语法 `?status=a,b` | 简单枚举 | 直观 | 组合能力弱 | 明确 AND/OR 语义 |\r\n| 过滤语法 `?filter[status]=a` | 复杂组合 | 可扩展 | 学习成本 | 需在文档中给出语法 |\r\n| 排序 `?sort=-created_at` | 通用 | 简单 | 多字段时歧义 | 白名单字段，禁止任意列 |\r\n\r\n**必须写进文档的三件事**\r\n1. 默认排序是什么（不写默认的排序等于随机顺序，客户端无法依赖）\r\n2. 分页上限与深翻页行为（offset 超过阈值应返回 400 而非慢查询）\r\n3. 游标有效期（过期应返回明确错误码，而不是静默从第一页开始）\r\n\r\n### Example 4: 保险保单查询 API（含幂等与版本策略）\r\n\r\n**Input:**\r\n```\r\n设计一个保单查询接口：\r\n- 按保单号查询单张保单，按客户号查询名下保单列表\r\n- 需要 OAuth2 client_credentials\r\n- 涉及客户敏感信息，需要字段级脱敏\r\n- 未来会增加\"理赔记录\"字段\r\n```\r\n\r\n**Output（要点摘录）:**\r\n```yaml\r\npaths:\r\n /v1/policies/{policyNo}:\r\n get:\r\n operationId: getPolicy\r\n security: [{ oauth2: [policy:read] }]\r\n parameters:\r\n - name: policyNo\r\n in: path\r\n required: true\r\n schema: { type: string, pattern: '^POL-[0-9]{6}$' }\r\n - name: fields\r\n in: query\r\n description: 指定返回字段，缺省返回非敏感字段\r\n schema: { type: array, items: { type: string } }\r\n responses:\r\n '200':\r\n description: 保单详情（敏感字段按 scope 脱敏）\r\n content:\r\n application/json:\r\n schema: { $ref: '#/components/schemas/Policy' }\r\n '403':\r\n description: 缺少 policy:read 或 policy:read.pii scope\r\n '404':\r\n description: 保单不存在\r\n```\r\n\r\n**设计要点说明**\r\n1. **字段级脱敏通过 scope 控制**：`policy:read` 返回脱敏视图（证件号 `110***********1234`），\r\n `policy:read.pii` 才返回完整值。脱敏规则写在文档里，不要让调用方猜。\r\n2. **pattern 约束**：保单号格式在 schema 里约束，避免无效请求打到数据库。\r\n3. **向前兼容**：新增\"理赔记录\"用 `fields=claims` 显式索取，不塞进默认响应。\r\n 这样老调用方的响应体不会变化。\r\n4. **幂等性**：GET 天然幂等；若未来加 `POST /v1/policies/{no}/sync`，\r\n 必须支持 `Idempotency-Key` 头并在文档中说明保留时长。\r\n5. **写文件/发布前**：以上为草稿，需用户确认后再落入仓库或发布到门户。\r\n\r\n### Example 5: 判断一次改动是不是破坏性变更\r\n\r\n**Input:**\r\n```\r\n我们准备把 /v1/policies 的响应里 holder_name 拆成 first_name 和 last_name，\r\n同时保留 holder_name。另外 status 枚举增加一个 lapsed。这两个改动能一起发吗？\r\n```\r\n\r\n**Output:**\r\n```\r\n拆成两个发布，理由如下：\r\n\r\n改动 A：holder_name 拆分，同时保留 holder_name\r\n 判定：非破坏性\r\n 依据：老字段保留，新增字段。老客户端不读新字段，不受影响。\r\n 风险：如果声明 holder_name 为 deprecated，需在 changelog 给出移除日期。\r\n 发布：可以走 Minor（v1.5.0）\r\n\r\n改动 B：status 枚举新增 lapsed\r\n 判定：破坏性（对严格解析的客户端）\r\n 依据：客户端若用 switch 且无 default 分支，遇到未知枚举值会抛异常或走错误分支。\r\n 风险等级：高——这个接口很可能被多个下游使用。\r\n 发布：需要 Major（v2.0.0），或先做两阶段：\r\n 阶段 1（v1.6.0）：公告枚举将扩展，要求下游客户端加 default 分支\r\n 阶段 2（v2.0.0）：正式加入 lapsed\r\n\r\n结论：不要一起发。\r\n 顺序：先发 A（Minor），再推动客户端容错，最后发 B（Major）。\r\n\r\n配套动作清单：\r\n- [ ] changelog 的 Deprecated 段标注 holder_name 移除计划（建议 ≥ 6 个月）\r\n- [ ] 给下游发送枚举扩展公告，附容错代码示例\r\n- [ ] 契约测试中加入\"未知枚举值不报错\"的用例\r\n- [ ] 监控 v1 与 v2 的调用量，确认迁移完成后再下线 v1\r\n\r\n判断破坏性的通用口诀：\r\n 老客户端不改代码还能正常用 → 非破坏性\r\n 老客户端不改代码可能出错 → 破坏性\r\n```\r\n\r\n### Example 6: 把一份真实接口文档改造成可对外发布的版本\r\n\r\n**Input:**\r\n```\r\n我把内部接口的 curl 示例直接贴到对外文档里了，被安全同事拦下。\r\n要改哪些地方？\r\n```\r\n\r\n**Output:**\r\n```\r\n按下面四步逐项过，每一步都能自动化检查：\r\n\r\n1. 域名与凭证\r\n - 内部域名（含 .internal、IP、真实主机名）→ 换成对外域名\r\n - 真实 token / 密钥 → 换成 或 $TOKEN，并说明注入方式\r\n - Basic 认证里出现的真实用户名密码 → 删除\r\n\r\n2. 请求与响应体\r\n - 保单号、身份证号、手机号、银行卡号、姓名、地址 → 合成值\r\n - 合成值要\"一眼假\"：POL-000001、138****0000、张三（示例）\r\n - 内部专用字段（如 internal_score、渠道佣金）→ 从对外 schema 移除\r\n\r\n3. 错误与边界\r\n - 只给了 200 的示例 → 补齐 401 / 403 / 429，尤其是 429 的 Retry-After\r\n - 错误体缺 request_id → 补上，并说明排障时提供该 ID\r\n\r\n4. 发布前\r\n - 标注 API 的可见范围（public / partner / internal）\r\n - 内部 schema 不得直接复用于对外文档，需单独评审\r\n - 生成物先预览，经你确认后再落盘或发布到门户\r\n\r\n一个可执行的自检：把文档 grep 一遍真实数据特征（18 位身份证、16 位卡号、\r\n11 位手机号、真实主机名）。能 grep 到就说明还没改完。\r\n```\r\n\r\n\r\n\r\n## Output Templates\r\n\r\n### Template: API Reference Page\r\n```markdown\r\n# {Endpoint Name}\r\n\r\n{Method} {Path}\r\n\r\n## Description\r\n{What this endpoint does}\r\n\r\n## Authentication\r\n{Authentication requirements}\r\n\r\n## Request\r\n\r\n### Path Parameters\r\n| Name | Type | Required | Description |\r\n|------|------|----------|-------------|\r\n| ... | ... | ... | ... |\r\n\r\n### Query Parameters\r\n| Name | Type | Required | Default | Description |\r\n|------|------|----------|---------|-------------|\r\n| ... | ... | ... | ... | ... |\r\n\r\n### Request Body\r\n```json\r\n{Request body schema}\r\n```\r\n\r\n## Response\r\n\r\n### 200 OK\r\n```json\r\n{Response schema}\r\n```\r\n\r\n### 400 Bad Request\r\n```json\r\n{\r\n \"error\": {\r\n \"code\": \"VALIDATION_ERROR\",\r\n \"message\": \"Description of the error\",\r\n \"details\": [...]\r\n }\r\n}\r\n```\r\n\r\n## Examples\r\n\r\n### Request\r\n```bash\r\ncurl -X {METHOD} {URL} \\\r\n -H \"Content-Type: application/json\" \\\r\n -H \"Authorization: Bearer \" \\\r\n -d '{body}'\r\n```\r\n\r\n### Response\r\n```json\r\n{response example}\r\n```\r\n```\r\n\r\n## Ecosystem Status (as of 2026-09-28 / 截至 2026-09-28)\r\n\r\nAPI specification tooling evolves continuously. Confirm against official\r\ndocumentation before locking in a choice.\r\n\r\n| 关注点 | 需要确认 | 影响 |\r\n|---|---|---|\r\n| OpenAPI 版本支持 | 你的文档门户/代码生成器支持 3.0 还是 3.1 | 决定规范版本选型 |\r\n| 规范 lint 规则集 | 采用哪套规则（如 Spectral 规则集） | 决定\"合规\"的判定标准 |\r\n| 契约测试落地 | 是否已有 broker 与 CI 集成 | 决定能否防止契约漂移 |\r\n| 数据脱敏要求 | 本单位对 PII 字段的对外暴露规则 | 影响示例与 schema 设计 |\r\n| 代码生成维护方式 | 生成代码是否入仓、如何评审 | 影响 SDK 交付流程 |\r\n\r\n**最近动态（截至 2026-09-28，以官方发布为准）**\r\n1. OpenAPI 3.1 与 JSON Schema 的对齐推动了工具链更新，但旧工具兼容性参差，\r\n 选型时普遍建议先验证门户与生成器支持情况。\r\n2. 规范即契约（spec-first）与契约测试的结合更为普遍，API 变更在 CI 阶段\r\n 就能发现破坏性改动，而不是等下游报错。\r\n3. 对接口中个人敏感信息字段的脱敏与最小暴露要求持续强化，字段级权限\r\n （按 scope 决定返回视图）成为常见做法。\r\n4. 规范即契约（spec-first）与 CI 阶段的破坏性变更检测结合得更紧密，很多团队\r\n 把 lint 规则和兼容性检查直接挂到 PR 门禁上，而不是依赖人工评审。\r\n5. 对外文档中的示例数据泄露成为常见安全发现，自动化扫描文档里的真实数据特征\r\n （证件号、卡号、手机号、内部主机名）正在成为发布流程的一环。\r\n6. 以上为趋势描述，具体规范版本与工具能力请以官方最新发布为准。\r\n\r\n## Best Practices\r\n\r\n### For API Design\r\n1. **Use nouns for resources:** `/users` not `/getUsers`\r\n2. **Plural naming:** `/tasks` not `/task`\r\n3. **Nest related resources:** `/users/{id}/tasks`\r\n4. **Version from day one:** `/v1`, `/v2`\r\n5. **Use appropriate HTTP methods:** GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)\r\n6. **Return proper status codes:** 200, 201, 400, 401, 403, 404, 500\r\n\r\n### For Documentation\r\n1. **Start with getting started:** Don't assume users know your API\r\n2. **Provide runnable examples:** Copy-paste ready code beats prose\r\n3. **Document errors clearly:** Users will hit them\r\n4. **Keep it updated:** Outdated docs are worse than no docs\r\n5. **Include changelog:** Help users track changes\r\n\r\n### For Security\r\n1. **Never log sensitive data:** Tokens, passwords, PII\r\n2. **Use HTTPS only:** No exceptions\r\n3. **Implement rate limiting:** Protect your infrastructure\r\n4. **Validate all input:** Never trust client data\r\n\r\n## Supported Standards\r\n\r\n| Standard | Support Level | 适用场景 | 典型工具链 | 注意事项 | 版本演进风险 |\r\n|---|---|---|---|---|---|\r\n| OpenAPI 3.0 | Full | 绝大多数 REST API | Swagger UI, Redoc, Prism, openapi-generator | 生态最成熟，兼容性最好 | 低（工具链稳定，生态成熟） |\r\n| OpenAPI 3.1 | Full | 需与 JSON Schema 2020-12 对齐 | 新版生成器、Spectral | 部分旧工具支持不完整，选型前先验证 | 中（旧工具支持度参差，需先验证） |\r\n| AsyncAPI 2.x | Full | 消息/事件驱动接口 | AsyncAPI Studio, Generator | 通道与绑定配置容易写错，需实测 | 中（通道与绑定配置易写错，需实测） |\r\n| GraphQL SDL | Full | 图查询接口 | Apollo, GraphiQL | 无内建版本机制，需自行约定演进策略 | 高（无内建版本机制，需自行约定演进策略） |\r\n| gRPC / Protobuf | Read/Convert | 内部高性能通信 | buf, grpc-gateway | 需额外生成 REST 网关才能对外 | 中（字段号一旦发布不可改语义） |\r\n| RAML | Read/Convert | 遗留项目 | raml2html | 新项目不建议采用 | 高（生态萎缩，新项目不建议） |\r\n| Swagger 2.0 | Read/Convert | 老系统迁移 | swagger2openapi | 建议转换为 3.x 后再维护 | 中（建议先转换为 3.x 再维护） |\r\n| JSON Schema | Full | 校验规则复用 | Ajv, jsonschema | 与 OpenAPI 3.0 的方言差异需注意 | 低（需锁定方言版本） |\r\n\r\n**版本选择建议**：对外新项目优先 3.1（与 JSON Schema 对齐），\r\n但如果你的文档门户或代码生成器只支持 3.0，就用 3.0——工具链兼容性\r\n带来的收益大于规范新特性。以所用工具的官方支持说明为准。\r\n\r\n## Supported Languages for Code Generation\r\n\r\n- Python (requests, httpx)\r\n- JavaScript (fetch, axios)\r\n- TypeScript\r\n- Go (net/http, gorilla)\r\n- Java (HttpClient, OkHttp)\r\n- C# (.NET HttpClient)\r\n- Ruby (Net::HTTP)\r\n- PHP (cURL)\r\n- curl\r\n- Kotlin\r\n\r\n## Version History\r\n\r\n- **1.0.1** (2026-09-10)\r\n - Added a data-handling front matter (no real credentials, no real customer\r\n data, minimise the paste, confirm before saving/publishing)\r\n - Added worked examples to all four feature groups (naming review + REST\r\n maturity self-check; quick-start with error cases + unified error shape;\r\n static vs dynamic mock comparison + fault injection; breaking-change\r\n classification + changelog format)\r\n - Added \"Status Code Selection Table\" (14 scenarios, 6 columns) and\r\n \"Pagination, Filtering & Sorting Cheat Sheet\"\r\n - Expanded standards table from 2 to 5 columns and 6 to 8 rows\r\n - Added Example 4 (insurance policy API with scope-based masking) and\r\n Example 5 (is this change breaking?)\r\n - Added \"Ecosystem Status (as of 2026-09-10)\"\r\n - Fixed a heading typo (`## Request}` → `## Request`)\r\n- **1.0.2** (2026-09-28)\r\n - Made example-vs-instruction status explicit: `DELETE /tasks/all` is now labelled\r\n a review counterexample to be rejected, not a pattern to implement, and the\r\n surrounding text states the skill issues no requests (TM1)\r\n - Added a URL/credential/sample-data placeholder table stating that example.com\r\n domains are reserved, tokens are placeholders, sample IDs are synthetic and all\r\n snippets are run-it-yourself reference material (E1)\r\n - Added a 文档示例必要性 column to the status-code table, a 发布前必备动作 column to\r\n the breaking-change table and a 版本演进风险 column to the standards table\r\n - Added Example 6 on converting an internal API doc into a publishable external one\r\n - Ecosystem status updated to 2026-09-28 with two added dynamics\r\n- **1.0.0** (2026-05-15): Initial release\r\n - OpenAPI 3.0/3.1 generation\r\n - Multi-language code samples\r\n - Documentation generation\r\n - Basic validation\r\n\r\n**Last Updated**: 2026-09-28\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn74e704j3ygjcygnpf02rdvd185js13\",\n \"slug\": \"api-design-documentation\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1790573135811\n}\n\nFile v1.0.2:skill-card.md\n\n## Description:\n\nHelps design APIs and draft OpenAPI specifications, developer documentation, mock-server configurations, and SDK code examples.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gechengling](https://clawhub.ai/user/gechengling)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nBackend developers, API product managers, DevOps engineers, and technical writers use this skill to draft and review API contracts, documentation, mock-server setups, and client examples.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: API examples or pasted specifications may expose real credentials or customer data.\n\nMitigation: Use placeholder credentials and synthetic data; check drafts for sensitive information before sharing.\n\nRisk: Generated requests, repository changes, or publication steps may be unsafe or inaccurate.\n\nMitigation: Review generated artifacts and obtain explicit approval before running requests, writing to a repository, or publishing documentation.\n\n## Reference(s):\n\n- [ClawHub skill listing](https://clawhub.ai/gechengling/skills/api-design-documentation)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Configuration, Code, Shell commands, Guidance]\n\n**Output Format:** [Markdown with OpenAPI YAML or JSON and code examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Drafts for review before execution or publication]\n\n## Skill Version(s):\n\n1.0.2 (source: ClawHub release and skill frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.1: 3 files, 13706 bytes\n\nFiles: skill-card.md (2150b), SKILL.md (27129b), _meta.json (143b)\n\nFile v1.0.1:SKILL.md\n\n---\r\nname: \"API Design & Documentation Generator\"\r\ndescription: \"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文档.\"\r\nversion: \"1.0.1\"\r\n---\r\n\r\n# API Design & Documentation Generator\r\n\r\n## Overview\r\n\r\nStop 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.\r\n\r\n## Triggers\r\n\r\n- 中文触发词：`API文档`、`接口文档`、`生成OpenAPI`、`API设计`、`Swagger文档`、`接口规范`、`API教程`、`GraphQL文档`\r\n- English triggers: `API documentation`, `OpenAPI spec`, `REST API design`, `Swagger docs`, `API reference`, `generate API docs`, `API guide`, `mock server`\r\n\r\n## Data Handling Note (read first / 前置声明)\r\n\r\nAPI specs and examples frequently leak real data. Before pasting anything:\r\n\r\n1. **Never include real credentials** — no production tokens, API keys, client\r\n secrets, or connection strings. Use ``, `${API_KEY}` placeholders.\r\n2. **No real customer data in examples** — 保单号、身份证号、手机号、银行卡号、\r\n 姓名、地址 must be replaced with obvious synthetic values (`POL-000001`,\r\n `138****0000`).\r\n3. **Minimise the paste** — when you only need help with one endpoint, paste that\r\n endpoint, not the whole 3,000-line spec.\r\n4. **Saving artifacts** — generated specs, Postman collections and mock servers\r\n are drafts. Show them to the user and get explicit confirmation before writing\r\n to a repository, publishing to a portal, or sending to a third party.\r\n5. **Internal-only APIs** — mark them as such in `info.description`; do not reuse\r\n internal schemas in public docs without a review pass.\r\n\r\nCode and specs in this document are reference material for you to run in your own\r\nenvironment; this skill does not execute them on your behalf.\r\n\r\n## Features\r\n\r\n### 1. API Design Intelligence\r\n- Generate OpenAPI 3.0/3.1 specs from descriptions or existing code\r\n- Validate API designs against best practices (REST maturity, naming conventions)\r\n- Suggest improvements for security, performance, and developer experience\r\n- Convert between OpenAPI, AsyncAPI, and GraphQL SDL\r\n\r\n\r\n**Worked example — naming and structure review**\r\n\r\n| 原始设计 | 问题 | 建议改法 | 理由 |\r\n|---|---|---|---|\r\n| `POST /getTasks` | 动词作资源名 | `GET /tasks` | 方法已表达动作 |\r\n| `GET /task/{id}` | 单复数不一致 | `GET /tasks/{id}` | 集合/成员关系清晰 |\r\n| `POST /tasks/update` | 用 POST 表达更新 | `PATCH /tasks/{id}` | 语义可被缓存与幂等推理 |\r\n| `GET /users/{id}/getOrders` | 嵌套层再带动词 | `GET /users/{id}/orders` | 层级已表达归属 |\r\n| `DELETE /tasks/all` | 危险且语义模糊 | 显式批量接口 + 确认令牌 | 避免误删且可审计 |\r\n| `/v1/tasks` 与 `/tasks` 并存 | 双版本无迁移计划 | 明确弃用时间表 | 否则长期维护两套 |\r\n\r\n**REST 成熟度自评（Richardson 0–3）**\r\n- L0：单一端点 + POST 全包 → 建议至少升到 L1\r\n- L1：有资源划分 → 多数内部系统够用\r\n- L2：正确使用 HTTP 方法与状态码 → 对外 API 的及格线\r\n- L3：HATEOAS 超媒体 → 收益常被高估，仅在需要强Discoverability时引入\r\n判据：对外 API 至少 L2；内部高频接口 L1 也可接受，不要为成熟度而成熟度。\r\n\r\n\r\n### 2. Documentation Generation\r\n- Write comprehensive API reference documentation\r\n- Create getting-started guides and tutorials\r\n- Generate authentication and authorization guides\r\n- Produce code samples in 10+ languages (Python, JavaScript, TypeScript, Go, Java, C#, Ruby, PHP, curl, etc.)\r\n- Create Postman collections and Insomnia specifications\r\n\r\n\r\n**Worked example — 一段\"可直接复制\"的快速上手（含错误示例）**\r\n\r\n好的快速上手只需回答三件事：怎么认证、第一个请求长什么样、失败了看哪里。\r\n\r\n```markdown\r\n## 5 分钟上手\r\n1. 在控制台创建应用，取得 `client_id` 与 `client_secret`\r\n2. 换取 token：\r\n curl -X POST https://api.example.com/v1/oauth/token \\\r\n -d grant_type=client_credentials \\\r\n -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET\r\n3. 调用第一个接口：\r\n curl https://api.example.com/v1/policies/POL-000001 \\\r\n -H \"Authorization: Bearer $TOKEN\"\r\n\r\n失败时先看这三处：\r\n- 401：token 过期（默认 3600 秒）\r\n- 403：应用未订阅该 scope\r\n- 429：超出配额，响应头 X-RateLimit-Reset 给出重置时间\r\n```\r\n\r\n常见缺陷：只给成功示例。开发者遇到错误时的第一反应是查文档，\r\n文档里没有 401/429 的示例，就会去开支持工单——这是文档成本最高的失败模式。\r\n\r\n**错误响应统一格式（推荐）**\r\n\r\n```json\r\n{\r\n \"error\": {\r\n \"code\": \"POLICY_NOT_FOUND\",\r\n \"message\": \"Policy POL-000001 does not exist\",\r\n \"request_id\": \"req_9f2c1a\",\r\n \"details\": [\r\n { \"field\": \"policy_no\", \"issue\": \"not_found\" }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n关键三项：`code` 供程序分支，`message` 给人看，`request_id` 供排查。\r\n三者缺一，排障成本都会显著上升。\r\n\r\n\r\n### 3. Mock Server Setup\r\n- Generate mock server code from OpenAPI specs\r\n- Support for static and dynamic mocking\r\n- Create sample request/response pairs\r\n- Set up delay rules for realistic testing\r\n\r\n\r\n**Worked example — 静态与动态 mock 的选择**\r\n\r\n| 维度 | 静态 mock | 动态 mock（规则/脚本） | 契约测试 |\r\n|---|---|---|---|\r\n| 实现成本 | 最低（示例文件即可） | 中 | 较高 |\r\n| 能否覆盖状态流转 | 否 | 能 | 能 |\r\n| 前端联调 | 够用 | 更好 | 不必要 |\r\n| 能否发现契约漂移 | 不能 | 弱 | 能 |\r\n| 典型工具形态 | Prism 静态示例、WireMock 固定桩 | Prism 动态、MSW | Pact / Schemathesis |\r\n\r\n建议：前端联调用静态 mock 起步（当天可用），一旦出现\"状态流转测不了\"\r\n（例如 创建→支付→退款）再升到动态 mock，最后对核心链路补契约测试。\r\n\r\n**延迟与故障注入（常被忽略但价值最高）**\r\n\r\n```yaml\r\n# 概念配置，按你的 mock 工具语法调整\r\nrules:\r\n - path: /v1/policies\r\n delay_ms: [120, 400] # 模拟真实网络区间，不是固定值\r\n - path: /v1/payments\r\n fault:\r\n rate: 0.05 # 5% 注入 503\r\n response: { error: { code: \"UPSTREAM_UNAVAILABLE\" } }\r\n```\r\n\r\n只测\"全部成功\"的客户端，上线后第一次遇到 5% 失败往往直接雪崩。\r\n\r\n\r\n### 4. API Quality Assurance\r\n- Validate OpenAPI/AsyncAPI syntax\r\n- Check for common anti-patterns\r\n- Ensure backward compatibility\r\n- Generate changelog drafts for API updates\r\n\r\n\r\n**Worked example — 破坏性变更分类表**\r\n\r\n| 变更 | 是否破坏性 | 判定依据 | 处理方式 |\r\n|---|---|---|---|\r\n| 新增可选请求字段 | 否 | 老客户端不传仍可用 | 直接发布 |\r\n| 新增响应字段 | 视客户端 | 严格解析的客户端可能报错 | 公告 + 观察 |\r\n| 新增端点 | 否 | 不影响既有调用 | 直接发布 |\r\n| 新增枚举值 | 是 | 老客户端 switch 无 default | 需 Major 或客户端先容错 |\r\n| 删除响应字段 | 是 | 依赖该字段者崩溃 | Major + 弃用期 |\r\n| 字段改类型（string→int） | 是 | 反序列化失败 | Major |\r\n| 收紧校验（允许空→必填） | 是 | 老请求被拒 | Major |\r\n| 放宽校验（必填→可选） | 否 | 更宽松 | 可 Minor |\r\n| 改错误码 | 是（软） | 依赖 code 分支者失效 | 保留旧码一个周期 |\r\n| 改分页默认值 | 是（软） | 行为静默变化 | 公告 + 双写观察 |\r\n\r\n**Changelog 草稿格式建议**\r\n\r\n```markdown\r\n## 2026-09-10 v1.4.0\r\n### Added\r\n- `GET /v1/policies/{no}/claims` 支持 `status` 过滤\r\n### Changed（非破坏性）\r\n- 列表接口默认 limit 由 20 调整为 50（可通过 limit 显式指定）\r\n### Deprecated\r\n- `GET /v1/policy` 将于 2027-03-31 移除，请使用 `/v1/policies`\r\n### Removed\r\n- 无\r\n```\r\n\r\n要点：`Deprecated` 必须带日期；没有日期的弃用等于没有弃用。\r\n\r\n\r\n## Workflow\r\n\r\n### API Documentation Workflow\r\n\r\n```\r\n1. INPUT: API description or existing code\r\n ↓\r\n2. DESIGN: Generate OpenAPI specification\r\n - Define endpoints\r\n - Schema definitions\r\n - Authentication/authorization\r\n - Error responses\r\n ↓\r\n3. VALIDATE: Check design quality\r\n - REST best practices\r\n - Security considerations\r\n - Completeness check\r\n ↓\r\n4. DOCUMENT: Generate comprehensive docs\r\n - Reference documentation\r\n - Quick-start guides\r\n - Code samples\r\n - Tutorials\r\n ↓\r\n5. TEST: Create mock server + test cases\r\n```\r\n\r\n### Quick API Spec Generation Workflow\r\n\r\n```\r\nStep 1: Describe your API\r\n├── What does it do?\r\n├── Who uses it?\r\n└── What data does it manage?\r\n\r\nStep 2: Define endpoints\r\n├── Resources (nouns, not verbs)\r\n├── CRUD operations\r\n└── Query parameters\r\n\r\nStep 3: Specify data models\r\n├── Request/response schemas\r\n├── Validation rules\r\n└── Error formats\r\n\r\nStep 4: Add security\r\n├── Authentication method\r\n├── Authorization scopes\r\n└── Rate limiting\r\n\r\nStep 5: Generate artifacts\r\n├── OpenAPI spec (YAML/JSON)\r\n├── Documentation\r\n└── Code samples\r\n```\r\n\r\n## Status Code Selection Table\r\n\r\n| 场景 | 状态码 | 含义 | 常见误用 | 客户端是否可重试 | 客户端应如何处理 |\r\n|---|---|---|---|---|---|\r\n| 查询成功 | 200 | 有响应体 | 用 200 返回错误体 | — | 正常解析 |\r\n| 创建成功 | 201 | 带 Location 指向新资源 | 返回 200 但不给 ID | — | 读取 Location |\r\n| 已接受、异步处理 | 202 | 未完成的受理 | 用 200 假装同步完成 | — | 轮询任务状态 |\r\n| 成功但无响应体 | 204 | 空体 | 返回 204 还带 body | — | 不解析 body |\r\n| 参数错误 | 400 | 客户端问题 | 用 500 掩盖校验失败 | 否 | 修正参数 |\r\n| 未认证 | 401 | 缺少/无效凭证 | 与 403 混用 | 否 | 重新认证 |\r\n| 无权限 | 403 | 认证成功但不够 | 用 404 隐藏存在性 | 否 | 申请 scope |\r\n| 资源不存在 | 404 | 路径或资源无 | 所有错误都返 404 | 否 | 不重试 |\r\n| 冲突（唯一约束/版本） | 409 | 状态冲突 | 用 400 | 否 | 读取当前状态后重试 |\r\n| 请求体无法处理（语义） | 422 | 语法对、语义错 | 与 400 混用 | 否 | 修正语义 |\r\n| 限流 | 429 | 超配额 | 用 503 | 是（按 Retry-After） | 退避重试 |\r\n| 服务端错误 | 500 | 未处理异常 | 把业务错误都归 500 | 视情况 | 携带 request_id 报障 |\r\n| 依赖不可用 | 503 | 下游故障/维护 | 与 500 不分 | 是（退避） | 退避并告警 |\r\n| 网关超时 | 504 | 上游超时 | 归为 500 | 是（谨慎） | 确认幂等后重试 |\r\n\r\n**两条硬规则**\r\n1. 4xx 表示\"客户端改了才能成功\"，5xx 表示\"客户端不改也可能成功\"。\r\n 混淆这两类是 API 语义最常见的缺陷。\r\n2. 所有 5xx 与 429 的响应体必须带可关联的 `request_id`，否则无法排障。\r\n\r\n## Input Examples\r\n\r\n### Example 1: API Description to OpenAPI\r\n\r\n**Input:**\r\n```\r\nDesign a REST API for a task management system.\r\n- Users can create, read, update, delete tasks\r\n- Tasks have: title, description, due_date, priority, status, tags\r\n- Support pagination for listing tasks\r\n- Require JWT authentication\r\n```\r\n\r\n**Expected Output (OpenAPI 3.0):**\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: Task Management API\r\n version: 1.0.0\r\n description: API for managing tasks with full CRUD operations\r\n\r\npaths:\r\n /tasks:\r\n get:\r\n summary: List all tasks\r\n parameters:\r\n - name: page\r\n in: query\r\n schema:\r\n type: integer\r\n default: 1\r\n - name: limit\r\n in: query\r\n schema:\r\n type: integer\r\n default: 20\r\n responses:\r\n '200':\r\n description: List of tasks\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Task'\r\n pagination:\r\n $ref: '#/components/schemas/Pagination'\r\n post:\r\n summary: Create a new task\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n required: [title]\r\n properties:\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n enum: [low, medium, high]\r\n responses:\r\n '201':\r\n description: Task created\r\n\r\n /tasks/{id}:\r\n get:\r\n summary: Get a task by ID\r\n parameters:\r\n - name: id\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n responses:\r\n '200':\r\n description: Task details\r\n '404':\r\n description: Task not found\r\n\r\ncomponents:\r\n schemas:\r\n Task:\r\n type: object\r\n properties:\r\n id:\r\n type: string\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n status:\r\n type: string\r\n tags:\r\n type: array\r\n items:\r\n type: string\r\n Pagination:\r\n type: object\r\n properties:\r\n page:\r\n type: integer\r\n limit:\r\n type: integer\r\n total:\r\n type: integer\r\n securitySchemes:\r\n BearerAuth:\r\n type: http\r\n scheme: bearer\r\n bearerFormat: JWT\r\n```\r\n\r\n### Example 2: Generate Documentation from OpenAPI\r\n\r\n**Input:** OpenAPI spec (above YAML)\r\n\r\n**Expected Output Sections:**\r\n```markdown\r\n# Task Management API Documentation\r\n\r\n## Getting Started\r\n\r\n### Authentication\r\nAll endpoints require a valid JWT token in the Authorization header:\r\n```\r\nAuthorization: Bearer \r\n```\r\n\r\n### Base URL\r\n```\r\nProduction: https://api.tasks.example.com/v1\r\n```\r\n\r\n## Endpoints\r\n\r\n### List Tasks\r\nRetrieves a paginated list of all tasks.\r\n\r\n**Request**\r\n```bash\r\ncurl -X GET \"https://api.tasks.example.com/v1/tasks?page=1&limit=20\" \\\r\n -H \"Authorization: Bearer \"\r\n```\r\n\r\n**Response**\r\n```json\r\n{\r\n \"data\": [\r\n {\r\n \"id\": \"task_123\",\r\n \"title\": \"Complete API docs\",\r\n \"priority\": \"high\",\r\n \"status\": \"pending\"\r\n }\r\n ],\r\n \"pagination\": {\r\n \"page\": 1,\r\n \"limit\": 20,\r\n \"total\": 45\r\n }\r\n}\r\n```\r\n\r\n## Code Samples\r\n\r\n### Python\r\n```python\r\nimport requests\r\n\r\nresponse = requests.get(\r\n \"https://api.tasks.example.com/v1/tasks\",\r\n headers={\"Authorization\": \"Bearer \"}\r\n)\r\ntasks = response.json()\r\n```\r\n\r\n### JavaScript\r\n```javascript\r\nconst response = await fetch(\r\n 'https://api.tasks.example.com/v1/tasks',\r\n {\r\n headers: { 'Authorization': 'Bearer ' }\r\n }\r\n);\r\nconst { data: tasks } = await response.json();\r\n```\r\n```\r\n\r\n### Example 3: Code Sample Generation\r\n\r\n**Input:** OpenAPI endpoint definition + language (Python)\r\n\r\n**Output:** Complete, runnable code snippet with error handling\r\n\r\n## Pagination, Filtering & Sorting Cheat Sheet\r\n\r\n| 方案 | 适用场景 | 优点 | 缺点 | 关键实现约束 |\r\n|---|---|---|---|---|\r\n| Offset 分页 (`page`/`limit`) | 后台管理、数据量小 | 可跳页、易理解 | 深翻页慢、数据变动会错位 | 需限制最大 offset |\r\n| Cursor 分页 (`cursor`/`limit`) | 列表流、大数据量 | 稳定、性能好 | 不能跳页 | cursor 必须不透明且可校验 |\r\n| Keyset / 时间续传 | 导出、对账 | 无重复无遗漏 | 实现复杂 | 排序键需唯一（含 tie-breaker） |\r\n| 总数返回 | 管理后台 | 便于分页控件 | 全表 count 昂贵 | 可返回估算值并标注 |\r\n| 过滤语法 `?status=a,b` | 简单枚举 | 直观 | 组合能力弱 | 明确 AND/OR 语义 |\r\n| 过滤语法 `?filter[status]=a` | 复杂组合 | 可扩展 | 学习成本 | 需在文档中给出语法 |\r\n| 排序 `?sort=-created_at` | 通用 | 简单 | 多字段时歧义 | 白名单字段，禁止任意列 |\r\n\r\n**必须写进文档的三件事**\r\n1. 默认排序是什么（不写默认的排序等于随机顺序，客户端无法依赖）\r\n2. 分页上限与深翻页行为（offset 超过阈值应返回 400 而非慢查询）\r\n3. 游标有效期（过期应返回明确错误码，而不是静默从第一页开始）\r\n\r\n### Example 4: 保险保单查询 API（含幂等与版本策略）\r\n\r\n**Input:**\r\n```\r\n设计一个保单查询接口：\r\n- 按保单号查询单张保单，按客户号查询名下保单列表\r\n- 需要 OAuth2 client_credentials\r\n- 涉及客户敏感信息，需要字段级脱敏\r\n- 未来会增加\"理赔记录\"字段\r\n```\r\n\r\n**Output（要点摘录）:**\r\n```yaml\r\npaths:\r\n /v1/policies/{policyNo}:\r\n get:\r\n operationId: getPolicy\r\n security: [{ oauth2: [policy:read] }]\r\n parameters:\r\n - name: policyNo\r\n in: path\r\n required: true\r\n schema: { type: string, pattern: '^POL-[0-9]{6}$' }\r\n - name: fields\r\n in: query\r\n description: 指定返回字段，缺省返回非敏感字段\r\n schema: { type: array, items: { type: string } }\r\n responses:\r\n '200':\r\n description: 保单详情（敏感字段按 scope 脱敏）\r\n content:\r\n application/json:\r\n schema: { $ref: '#/components/schemas/Policy' }\r\n '403':\r\n description: 缺少 policy:read 或 policy:read.pii scope\r\n '404':\r\n description: 保单不存在\r\n```\r\n\r\n**设计要点说明**\r\n1. **字段级脱敏通过 scope 控制**：`policy:read` 返回脱敏视图（证件号 `110***********1234`），\r\n `policy:read.pii` 才返回完整值。脱敏规则写在文档里，不要让调用方猜。\r\n2. **pattern 约束**：保单号格式在 schema 里约束，避免无效请求打到数据库。\r\n3. **向前兼容**：新增\"理赔记录\"用 `fields=claims` 显式索取，不塞进默认响应。\r\n 这样老调用方的响应体不会变化。\r\n4. **幂等性**：GET 天然幂等；若未来加 `POST /v1/policies/{no}/sync`，\r\n 必须支持 `Idempotency-Key` 头并在文档中说明保留时长。\r\n5. **写文件/发布前**：以上为草稿，需用户确认后再落入仓库或发布到门户。\r\n\r\n### Example 5: 判断一次改动是不是破坏性变更\r\n\r\n**Input:**\r\n```\r\n我们准备把 /v1/policies 的响应里 holder_name 拆成 first_name 和 last_name，\r\n同时保留 holder_name。另外 status 枚举增加一个 lapsed。这两个改动能一起发吗？\r\n```\r\n\r\n**Output:**\r\n```\r\n拆成两个发布，理由如下：\r\n\r\n改动 A：holder_name 拆分，同时保留 holder_name\r\n 判定：非破坏性\r\n 依据：老字段保留，新增字段。老客户端不读新字段，不受影响。\r\n 风险：如果声明 holder_name 为 deprecated，需在 changelog 给出移除日期。\r\n 发布：可以走 Minor（v1.5.0）\r\n\r\n改动 B：status 枚举新增 lapsed\r\n 判定：破坏性（对严格解析的客户端）\r\n 依据：客户端若用 switch 且无 default 分支，遇到未知枚举值会抛异常或走错误分支。\r\n 风险等级：高——这个接口很可能被多个下游使用。\r\n 发布：需要 Major（v2.0.0），或先做两阶段：\r\n 阶段 1（v1.6.0）：公告枚举将扩展，要求下游客户端加 default 分支\r\n 阶段 2（v2.0.0）：正式加入 lapsed\r\n\r\n结论：不要一起发。\r\n 顺序：先发 A（Minor），再推动客户端容错，最后发 B（Major）。\r\n\r\n配套动作清单：\r\n- [ ] changelog 的 Deprecated 段标注 holder_name 移除计划（建议 ≥ 6 个月）\r\n- [ ] 给下游发送枚举扩展公告，附容错代码示例\r\n- [ ] 契约测试中加入\"未知枚举值不报错\"的用例\r\n- [ ] 监控 v1 与 v2 的调用量，确认迁移完成后再下线 v1\r\n\r\n判断破坏性的通用口诀：\r\n 老客户端不改代码还能正常用 → 非破坏性\r\n 老客户端不改代码可能出错 → 破坏性\r\n```\r\n\r\n## Output Templates\r\n\r\n### Template: API Reference Page\r\n```markdown\r\n# {Endpoint Name}\r\n\r\n{Method} {Path}\r\n\r\n## Description\r\n{What this endpoint does}\r\n\r\n## Authentication\r\n{Authentication requirements}\r\n\r\n## Request\r\n\r\n### Path Parameters\r\n| Name | Type | Required | Description |\r\n|------|------|----------|-------------|\r\n| ... | ... | ... | ... |\r\n\r\n### Query Parameters\r\n| Name | Type | Required | Default | Description |\r\n|------|------|----------|---------|-------------|\r\n| ... | ... | ... | ... | ... |\r\n\r\n### Request Body\r\n```json\r\n{Request body schema}\r\n```\r\n\r\n## Response\r\n\r\n### 200 OK\r\n```json\r\n{Response schema}\r\n```\r\n\r\n### 400 Bad Request\r\n```json\r\n{\r\n \"error\": {\r\n \"code\": \"VALIDATION_ERROR\",\r\n \"message\": \"Description of the error\",\r\n \"details\": [...]\r\n }\r\n}\r\n```\r\n\r\n## Examples\r\n\r\n### Request\r\n```bash\r\ncurl -X {METHOD} {URL} \\\r\n -H \"Content-Type: application/json\" \\\r\n -H \"Authorization: Bearer \" \\\r\n -d '{body}'\r\n```\r\n\r\n### Response\r\n```json\r\n{response example}\r\n```\r\n```\r\n\r\n## Ecosystem Status (as of 2026-09-10 / 截至 2026-09-10)\r\n\r\nAPI specification tooling evolves continuously. Confirm against official\r\ndocumentation before locking in a choice.\r\n\r\n| 关注点 | 需要确认 | 影响 |\r\n|---|---|---|\r\n| OpenAPI 版本支持 | 你的文档门户/代码生成器支持 3.0 还是 3.1 | 决定规范版本选型 |\r\n| 规范 lint 规则集 | 采用哪套规则（如 Spectral 规则集） | 决定\"合规\"的判定标准 |\r\n| 契约测试落地 | 是否已有 broker 与 CI 集成 | 决定能否防止契约漂移 |\r\n| 数据脱敏要求 | 本单位对 PII 字段的对外暴露规则 | 影响示例与 schema 设计 |\r\n| 代码生成维护方式 | 生成代码是否入仓、如何评审 | 影响 SDK 交付流程 |\r\n\r\n**最近动态（截至 2026-09-10，以官方发布为准）**\r\n1. OpenAPI 3.1 与 JSON Schema 的对齐推动了工具链更新，但旧工具兼容性参差，\r\n 选型时普遍建议先验证门户与生成器支持情况。\r\n2. 规范即契约（spec-first）与契约测试的结合更为普遍，API 变更在 CI 阶段\r\n 就能发现破坏性改动，而不是等下游报错。\r\n3. 对接口中个人敏感信息字段的脱敏与最小暴露要求持续强化，字段级权限\r\n （按 scope 决定返回视图）成为常见做法。\r\n4. 以上为趋势描述，具体规范版本与工具能力请以官方最新发布为准。\r\n\r\n## Best Practices\r\n\r\n### For API Design\r\n1. **Use nouns for resources:** `/users` not `/getUsers`\r\n2. **Plural naming:** `/tasks` not `/task`\r\n3. **Nest related resources:** `/users/{id}/tasks`\r\n4. **Version from day one:** `/v1`, `/v2`\r\n5. **Use appropriate HTTP methods:** GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)\r\n6. **Return proper status codes:** 200, 201, 400, 401, 403, 404, 500\r\n\r\n### For Documentation\r\n1. **Start with getting started:** Don't assume users know your API\r\n2. **Provide runnable examples:** Copy-paste ready code beats prose\r\n3. **Document errors clearly:** Users will hit them\r\n4. **Keep it updated:** Outdated docs are worse than no docs\r\n5. **Include changelog:** Help users track changes\r\n\r\n### For Security\r\n1. **Never log sensitive data:** Tokens, passwords, PII\r\n2. **Use HTTPS only:** No exceptions\r\n3. **Implement rate limiting:** Protect your infrastructure\r\n4. **Validate all input:** Never trust client data\r\n\r\n## Supported Standards\r\n\r\n| Standard | Support Level | 适用场景 | 典型工具链 | 注意事项 |\r\n|---|---|---|---|---|\r\n| OpenAPI 3.0 | Full | 绝大多数 REST API | Swagger UI, Redoc, Prism, openapi-generator | 生态最成熟，兼容性最好 |\r\n| OpenAPI 3.1 | Full | 需与 JSON Schema 2020-12 对齐 | 新版生成器、Spectral | 部分旧工具支持不完整，选型前先验证 |\r\n| AsyncAPI 2.x | Full | 消息/事件驱动接口 | AsyncAPI Studio, Generator | 通道与绑定配置容易写错，需实测 |\r\n| GraphQL SDL | Full | 图查询接口 | Apollo, GraphiQL | 无内建版本机制，需自行约定演进策略 |\r\n| gRPC / Protobuf | Read/Convert | 内部高性能通信 | buf, grpc-gateway | 需额外生成 REST 网关才能对外 |\r\n| RAML | Read/Convert | 遗留项目 | raml2html | 新项目不建议采用 |\r\n| Swagger 2.0 | Read/Convert | 老系统迁移 | swagger2openapi | 建议转换为 3.x 后再维护 |\r\n| JSON Schema | Full | 校验规则复用 | Ajv, jsonschema | 与 OpenAPI 3.0 的方言差异需注意 |\r\n\r\n**版本选择建议**：对外新项目优先 3.1（与 JSON Schema 对齐），\r\n但如果你的文档门户或代码生成器只支持 3.0，就用 3.0——工具链兼容性\r\n带来的收益大于规范新特性。以所用工具的官方支持说明为准。\r\n\r\n## Supported Languages for Code Generation\r\n\r\n- Python (requests, httpx)\r\n- JavaScript (fetch, axios)\r\n- TypeScript\r\n- Go (net/http, gorilla)\r\n- Java (HttpClient, OkHttp)\r\n- C# (.NET HttpClient)\r\n- Ruby (Net::HTTP)\r\n- PHP (cURL)\r\n- curl\r\n- Kotlin\r\n\r\n## Version History\r\n\r\n- **1.0.1** (2026-09-10)\r\n - Added a data-handling front matter (no real credentials, no real customer\r\n data, minimise the paste, confirm before saving/publishing)\r\n - Added worked examples to all four feature groups (naming review + REST\r\n maturity self-check; quick-start with error cases + unified error shape;\r\n static vs dynamic mock comparison + fault injection; breaking-change\r\n classification + changelog format)\r\n - Added \"Status Code Selection Table\" (14 scenarios, 6 columns) and\r\n \"Pagination, Filtering & Sorting Cheat Sheet\"\r\n - Expanded standards table from 2 to 5 columns and 6 to 8 rows\r\n - Added Example 4 (insurance policy API with scope-based masking) and\r\n Example 5 (is this change breaking?)\r\n - Added \"Ecosystem Status (as of 2026-09-10)\"\r\n - Fixed a heading typo (`## Request}` → `## Request`)\r\n- **1.0.0** (2026-05-15): Initial release\r\n - OpenAPI 3.0/3.1 generation\r\n - Multi-language code samples\r\n - Documentation generation\r\n - Basic validation\r\n\r\n**Last Updated**: 2026-09-10\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn74e704j3ygjcygnpf02rdvd185js13\",\n \"slug\": \"api-design-documentation\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1789018603863\n}\n\nFile v1.0.1:skill-card.md\n\n## Description:\n\nGenerates API designs, OpenAPI/AsyncAPI/GraphQL specifications, documentation, mock-server guidance, validation notes, and SDK/code snippets for API delivery teams.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gechengling](https://clawhub.ai/user/gechengling)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, API product managers, DevOps engineers, and technical writers use this skill to draft API specs, reference documentation, tutorials, mock-server plans, validation feedback, and code snippets before review and publication.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: API examples or pasted specifications can expose production tokens, API keys, customer PII, or confidential internal schemas.\n\nMitigation: Use placeholders and sanitized synthetic data, minimize pasted context, and avoid confidential schemas unless they have been reviewed for sharing.\n\nRisk: Generated specs, Postman collections, mock servers, and documentation drafts may be inaccurate or inappropriate to publish as-is.\n\nMitigation: Review generated artifacts and get explicit confirmation before writing them to a repository, publishing them to a portal, or sending them to a third party.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/gechengling/skills/api-design-documentation)\n- [Publisher profile](https://clawhub.ai/user/gechengling)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Code, Configuration, Shell commands, Guidance]\n\n**Output Format:** [Markdown with YAML, JSON, bash, and language-specific code blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Draft artifacts should be reviewed before being written to a repository, published to a portal, or shared externally.]\n\n## Skill Version(s):\n\n1.0.1 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.0: 3 files, 5405 bytes\n\nFiles: skill-card.md (1895b), SKILL.md (10711b), _meta.json (143b)\n\nFile v1.0.0:SKILL.md\n\n---\r\nname: \"API Design & Documentation Generator\"\r\ndescription: \"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文档.\"\r\nversion: \"1.0.0\"\r\n---\r\n\r\n# API Design & Documentation Generator\r\n\r\n## Overview\r\n\r\nStop 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.\r\n\r\n## Triggers\r\n\r\n- 中文触发词：`API文档`、`接口文档`、`生成OpenAPI`、`API设计`、`Swagger文档`、`接口规范`、`API教程`、`GraphQL文档`\r\n- English triggers: `API documentation`, `OpenAPI spec`, `REST API design`, `Swagger docs`, `API reference`, `generate API docs`, `API guide`, `mock server`\r\n\r\n## Features\r\n\r\n### 1. API Design Intelligence\r\n- Generate OpenAPI 3.0/3.1 specs from descriptions or existing code\r\n- Validate API designs against best practices (REST maturity, naming conventions)\r\n- Suggest improvements for security, performance, and developer experience\r\n- Convert between OpenAPI, AsyncAPI, and GraphQL SDL\r\n\r\n### 2. Documentation Generation\r\n- Write comprehensive API reference documentation\r\n- Create getting-started guides and tutorials\r\n- Generate authentication and authorization guides\r\n- Produce code samples in 10+ languages (Python, JavaScript, TypeScript, Go, Java, C#, Ruby, PHP, curl, etc.)\r\n- Create Postman collections and Insomnia specifications\r\n\r\n### 3. Mock Server Setup\r\n- Generate mock server code from OpenAPI specs\r\n- Support for static and dynamic mocking\r\n- Create sample request/response pairs\r\n- Set up delay rules for realistic testing\r\n\r\n### 4. API Quality Assurance\r\n- Validate OpenAPI/AsyncAPI syntax\r\n- Check for common anti-patterns\r\n- Ensure backward compatibility\r\n- Generate changelog drafts for API updates\r\n\r\n## Workflow\r\n\r\n### API Documentation Workflow\r\n\r\n```\r\n1. INPUT: API description or existing code\r\n ↓\r\n2. DESIGN: Generate OpenAPI specification\r\n - Define endpoints\r\n - Schema definitions\r\n - Authentication/authorization\r\n - Error responses\r\n ↓\r\n3. VALIDATE: Check design quality\r\n - REST best practices\r\n - Security considerations\r\n - Completeness check\r\n ↓\r\n4. DOCUMENT: Generate comprehensive docs\r\n - Reference documentation\r\n - Quick-start guides\r\n - Code samples\r\n - Tutorials\r\n ↓\r\n5. TEST: Create mock server + test cases\r\n```\r\n\r\n### Quick API Spec Generation Workflow\r\n\r\n```\r\nStep 1: Describe your API\r\n├── What does it do?\r\n├── Who uses it?\r\n└── What data does it manage?\r\n\r\nStep 2: Define endpoints\r\n├── Resources (nouns, not verbs)\r\n├── CRUD operations\r\n└── Query parameters\r\n\r\nStep 3: Specify data models\r\n├── Request/response schemas\r\n├── Validation rules\r\n└── Error formats\r\n\r\nStep 4: Add security\r\n├── Authentication method\r\n├── Authorization scopes\r\n└── Rate limiting\r\n\r\nStep 5: Generate artifacts\r\n├── OpenAPI spec (YAML/JSON)\r\n├── Documentation\r\n└── Code samples\r\n```\r\n\r\n## Input Examples\r\n\r\n### Example 1: API Description to OpenAPI\r\n\r\n**Input:**\r\n```\r\nDesign a REST API for a task management system.\r\n- Users can create, read, update, delete tasks\r\n- Tasks have: title, description, due_date, priority, status, tags\r\n- Support pagination for listing tasks\r\n- Require JWT authentication\r\n```\r\n\r\n**Expected Output (OpenAPI 3.0):**\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: Task Management API\r\n version: 1.0.0\r\n description: API for managing tasks with full CRUD operations\r\n\r\npaths:\r\n /tasks:\r\n get:\r\n summary: List all tasks\r\n parameters:\r\n - name: page\r\n in: query\r\n schema:\r\n type: integer\r\n default: 1\r\n - name: limit\r\n in: query\r\n schema:\r\n type: integer\r\n default: 20\r\n responses:\r\n '200':\r\n description: List of tasks\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Task'\r\n pagination:\r\n $ref: '#/components/schemas/Pagination'\r\n post:\r\n summary: Create a new task\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n required: [title]\r\n properties:\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n enum: [low, medium, high]\r\n responses:\r\n '201':\r\n description: Task created\r\n\r\n /tasks/{id}:\r\n get:\r\n summary: Get a task by ID\r\n parameters:\r\n - name: id\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n responses:\r\n '200':\r\n description: Task details\r\n '404':\r\n description: Task not found\r\n\r\ncomponents:\r\n schemas:\r\n Task:\r\n type: object\r\n properties:\r\n id:\r\n type: string\r\n title:\r\n type: string\r\n description:\r\n type: string\r\n due_date:\r\n type: string\r\n format: date\r\n priority:\r\n type: string\r\n status:\r\n type: string\r\n tags:\r\n type: array\r\n items:\r\n type: string\r\n Pagination:\r\n type: object\r\n properties:\r\n page:\r\n type: integer\r\n limit:\r\n type: integer\r\n total:\r\n type: integer\r\n securitySchemes:\r\n BearerAuth:\r\n type: http\r\n scheme: bearer\r\n bearerFormat: JWT\r\n```\r\n\r\n### Example 2: Generate Documentation from OpenAPI\r\n\r\n**Input:** OpenAPI spec (above YAML)\r\n\r\n**Expected Output Sections:**\r\n```markdown\r\n# Task Management API Documentation\r\n\r\n## Getting Started\r\n\r\n### Authentication\r\nAll endpoints require a valid JWT token in the Authorization header:\r\n```\r\nAuthorization: Bearer \r\n```\r\n\r\n### Base URL\r\n```\r\nProduction: https://api.tasks.example.com/v1\r\n```\r\n\r\n## Endpoints\r\n\r\n### List Tasks\r\nRetrieves a paginated list of all tasks.\r\n\r\n**Request**\r\n```bash\r\ncurl -X GET \"https://api.tasks.example.com/v1/tasks?page=1&limit=20\" \\\r\n -H \"Authorization: Bearer \"\r\n```\r\n\r\n**Response**\r\n```json\r\n{\r\n \"data\": [\r\n {\r\n \"id\": \"task_123\",\r\n \"title\": \"Complete API docs\",\r\n \"priority\": \"high\",\r\n \"status\": \"pending\"\r\n }\r\n ],\r\n \"pagination\": {\r\n \"page\": 1,\r\n \"limit\": 20,\r\n \"total\": 45\r\n }\r\n}\r\n```\r\n\r\n## Code Samples\r\n\r\n### Python\r\n```python\r\nimport requests\r\n\r\nresponse = requests.get(\r\n \"https://api.tasks.example.com/v1/tasks\",\r\n headers={\"Authorization\": \"Bearer \"}\r\n)\r\ntasks = response.json()\r\n```\r\n\r\n### JavaScript\r\n```javascript\r\nconst response = await fetch(\r\n 'https://api.tasks.example.com/v1/tasks',\r\n {\r\n headers: { 'Authorization': 'Bearer ' }\r\n }\r\n);\r\nconst { data: tasks } = await response.json();\r\n```\r\n```\r\n\r\n### Example 3: Code Sample Generation\r\n\r\n**Input:** OpenAPI endpoint definition + language (Python)\r\n\r\n**Output:** Complete, runnable code snippet with error handling\r\n\r\n## Output Templates\r\n\r\n### Template: API Reference Page\r\n```markdown\r\n# {Endpoint Name}\r\n\r\n{Method} {Path}\r\n\r\n## Description\r\n{What this endpoint does}\r\n\r\n## Authentication\r\n{Authentication requirements}\r\n\r\n## Request}\r\n\r\n### Path Parameters\r\n| Name | Type | Required | Description |\r\n|------|------|----------|-------------|\r\n| ... | ... | ... | ... |\r\n\r\n### Query Parameters\r\n| Name | Type | Required | Default | Description |\r\n|------|------|----------|---------|-------------|\r\n| ... | ... | ... | ... | ... |\r\n\r\n### Request Body\r\n```json\r\n{Request body schema}\r\n```\r\n\r\n## Response\r\n\r\n### 200 OK\r\n```json\r\n{Response schema}\r\n```\r\n\r\n### 400 Bad Request\r\n```json\r\n{\r\n \"error\": {\r\n \"code\": \"VALIDATION_ERROR\",\r\n \"message\": \"Description of the error\",\r\n \"details\": [...]\r\n }\r\n}\r\n```\r\n\r\n## Examples\r\n\r\n### Request\r\n```bash\r\ncurl -X {METHOD} {URL} \\\r\n -H \"Content-Type: application/json\" \\\r\n -H \"Authorization: Bearer \" \\\r\n -d '{body}'\r\n```\r\n\r\n### Response\r\n```json\r\n{response example}\r\n```\r\n```\r\n\r\n## Best Practices\r\n\r\n### For API Design\r\n1. **Use nouns for resources:** `/users` not `/getUsers`\r\n2. **Plural naming:** `/tasks` not `/task`\r\n3. **Nest related resources:** `/users/{id}/tasks`\r\n4. **Version from day one:** `/v1`, `/v2`\r\n5. **Use appropriate HTTP methods:** GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)\r\n6. **Return proper status codes:** 200, 201, 400, 401, 403, 404, 500\r\n\r\n### For Documentation\r\n1. **Start with getting started:** Don't assume users know your API\r\n2. **Provide runnable examples:** Copy-paste ready code beats prose\r\n3. **Document errors clearly:** Users will hit them\r\n4. **Keep it updated:** Outdated docs are worse than no docs\r\n5. **Include changelog:** Help users track changes\r\n\r\n### For Security\r\n1. **Never log sensitive data:** Tokens, passwords, PII\r\n2. **Use HTTPS only:** No exceptions\r\n3. **Implement rate limiting:** Protect your infrastructure\r\n4. **Validate all input:** Never trust client data\r\n\r\n## Supported Standards\r\n\r\n| Standard | Support Level |\r\n|----------|---------------|\r\n| OpenAPI 3.0 | Full |\r\n| OpenAPI 3.1 | Full |\r\n| AsyncAPI 2.0 | Full |\r\n| GraphQL SDL | Full |\r\n| RAML | Read/Convert |\r\n| Swagger 2.0 | Read/Convert |\r\n\r\n## Supported Languages for Code Generation\r\n\r\n- Python (requests, httpx)\r\n- JavaScript (fetch, axios)\r\n- TypeScript\r\n- Go (net/http, gorilla)\r\n- Java (HttpClient, OkHttp)\r\n- C# (.NET HttpClient)\r\n- Ruby (Net::HTTP)\r\n- PHP (cURL)\r\n- curl\r\n- Kotlin\r\n\r\n## Version History\r\n\r\n- **1.0.0** (2026-05-15): Initial release\r\n - OpenAPI 3.0/3.1 generation\r\n - Multi-language code samples\r\n - Documentation generation\r\n - Basic validation\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn74e704j3ygjcygnpf02rdvd185js13\",\n \"slug\": \"api-design-documentation\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1779197032203\n}\n\nFile v1.0.0:skill-card.md\n\n## Description:
\nAI-powered API design and documentation assistant that generates RESTful and OpenAPI specs, API documentation, mock-server guidance, validation feedback, and SDK code snippets.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[gechengling](https://clawhub.ai/user/gechengling)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, API product managers, DevOps engineers, and technical writers use this skill to design APIs, produce OpenAPI or related specifications, write developer-facing documentation, create examples, and validate API designs.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated code samples, authentication examples, or mock-server snippets may not match a project's security requirements.
\nMitigation: Review and harden generated examples before using them with real services.
\n\n\n## Reference(s):
\n- [Api Design Documentation on ClawHub](https://clawhub.ai/gechengling/api-design-documentation)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]
\n**Output Format:** [Markdown, YAML or JSON specifications, code snippets, and shell command examples]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May include OpenAPI, AsyncAPI, GraphQL SDL, API reference pages, tutorials, request and response examples, mock-server setup guidance, and SDK snippets.]
\n\n## Skill Version(s):
\n1.0.0 (source: server release metadata and frontmatter)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
","readmeExcerpt":"Skill: API Design & Documentation Generator Owner: gechengling Summary: 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 ","codeSnippets":[],"executableExamples":[],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: \"API Design & Documentation Generator\"\r\ndescription: \"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文档.\"\r\nversion: \"1.0.2\"\r\n---\r\n\r\n# API Design & Documentation Generator\r\n\r\n## Overview\r\n\r\nStop 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.\r\n\r\n## Triggers\r\n\r\n- 中文触发词：`API文档`、`接口文档`、`生成OpenAPI`、`API设计`、`Swagger文档`、`接口规范`、`API教程`、`GraphQL文档`\r\n- English triggers: `API documentation`, `OpenAPI spec`, `REST API design`, `Swagger docs`, `API reference`, `generate API docs`, `API guide`, `mock server`\r\n\r\n## Data Handling Note (read first / 前置声明)\r\n\r\nAPI specs and examples frequently leak real data. Before pasting anything:\r\n\r\n1. **Never include real credentials** — no production tokens, API keys, client\r\n secrets, or connection strings. Use ``, `${API_KEY}` placeholders.\r\n2. **No real customer data in examples** — 保单号、身份证号、手机号、银行卡号、\r\n 姓名、地址 must be replaced with obvious synthetic values (`POL-000001`,\r\n `138****0000`).\r\n3. **Minimise the paste** — when you only need help with one endpoint, paste that\r\n endpoint, not the whole 3,000-line spec.\r\n4. **Saving artifacts** — generated specs, Postman collections and mock servers\r\n are drafts. Show them to the user and get explicit confirmation before writing\r\n to a repository, publishing to a portal, or sending to a third party.\r\n5. **Internal-only APIs** — mark them as such in `info.description`; do not reuse\r\n internal schemas in public docs without a review pass.\r\n\r\nCode and specs in this document are reference material for you to run in your own\r\nenvironment; this skill does not execute them on your behalf.\r\n\r\n## Features\r\n\r\n### 1. API Design Intelligence\r\n- Generate OpenAPI 3.0/3.1 specs from descriptions or existing code\r\n- Validate API designs against best practices (REST maturity, naming conventions)\r\n- Suggest improvements for security, performance, and developer experience\r\n- Convert between OpenAPI, AsyncAPI, and GraphQL SDL\r\n\r\n\r\n**关于本表中的“危险示例”（重要）**\r\n\r\n下表出现的 `DELETE /tasks/all` 等写法，是**评审反例**，用来说明“什么样的设计应该被\r\n打回”。它不是可执行指令，本技能也不会替你发起任何请求。出现在此处的唯一目的是让你\r\n在 code review 中识别并否决这类设计。\r\n\r\n**关于全文的 URL、域名与凭证（重要）**\r\n\r\n| 出现的形式 | 性质 | 处理 |\r\n|---|---|---|\r\n| `api.example.com`、`api.tasks.example.com` | RFC 2606 保留示例域名，不可解析 | 替换为你自己的域名 |\r\n| ``、`$TOKEN`、`${API_KEY}`"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74e704j3ygjcygnpf02rdvd185js13\",\n \"slug\": \"api-design-documentation\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1790573135811\n}"},{"path":"skill-card.md","content":"## Description:\n\nHelps design APIs and draft OpenAPI specifications, developer documentation, mock-server configurations, and SDK code examples.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gechengling](https://clawhub.ai/user/gechengling)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nBackend developers, API product managers, DevOps engineers, and technical writers use this skill to draft and review API contracts, documentation, mock-server setups, and client examples.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: API examples or pasted specifications may expose real credentials or customer data.\n\nMitigation: Use placeholder credentials and synthetic data; check drafts for sensitive information before sharing.\n\nRisk: Generated requests, repository changes, or publication steps may be unsafe or inaccurate.\n\nMitigation: Review generated artifacts and obtain explicit approval before running requests, writing to a repository, or publishing documentation.\n\n## Reference(s):\n\n- [ClawHub skill listing](https://clawhub.ai/gechengling/skills/api-design-documentation)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Configuration, Code, Shell commands, Guidance]\n\n**Output Format:** [Markdown with OpenAPI YAML or JSON and code examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Drafts for review before execution or publication]\n\n## Skill Version(s):\n\n1.0.2 (source: ClawHub release and skill frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"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文档. Skill: API Design & Documentation Generator Owner: gechengling Summary: 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","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1116,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T19:38:43.026Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:41:28.943Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}