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 <token>, ${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.comRFC 2606 保留示例域名，不可解析替换为你自己的域名<token>、 $TOKEN、 ${API_KEY}、 <your_token>占位符，不是真实凭证运行时注入，绝不写进文档或仓库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 动态、MSWPact / 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#

text

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#

text

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:

text

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 <your_token>

text

### Base URL

Production: https://api.tasks.example.com/v1

text

## 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 <token>"

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 <token>"}
)
tasks = response.json()

JavaScript#

javascript

const response = await fetch(
  'https://api.tasks.example.com/v1/tasks',
  {
    headers: { 'Authorization': 'Bearer <token>' }
  }
);
const { data: tasks } = await response.json();

text

### 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
• 涉及客户敏感信息，需要字段级脱敏
• 未来会增加"理赔记录"字段

text

**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:

text

我们准备把 /v1/policies 的响应里 holder_name 拆成 first_name 和 last_name，
同时保留 holder_name。另外 status 枚举增加一个 lapsed。这两个改动能一起发吗？

Output:

text

拆成两个发布，理由如下：

改动 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:

text

我把内部接口的 curl 示例直接贴到对外文档里了，被安全同事拦下。
要改哪些地方？

Output:

text

按下面四步逐项过，每一步都能自动化检查：

1. 域名与凭证
   - 内部域名（含 .internal、IP、真实主机名）→ 换成对外域名
   - 真实 token / 密钥 → 换成 <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 <token>" \
  -d '{body}'

Response#

json

{response example}

text

## 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