技能使用指南

api-documentation（API文档编写）Skill 是什么？能一键写好 OpenAPI 规范吗？

API文档编写Skill基于OpenAPI 3.1与Swagger规范，一键生成端点文档、认证流程、错误处理、限流说明与SDK指南，覆盖Webhook、内容协商与版本迁移，产出可直接导入Swagger UI、Redoc的规范文件。想告别手写YAML、让文档与代码同步，点进来了解安装方式与实战用法。

API文档编写Skillapi-documentation
19 个章节 约 16 分钟阅读 AI 智能生成

API文档编写Skill：用 OpenAPI/Swagger 规范，把 REST API 一次讲清楚

  • 一句话定位：这是一个专注于 REST API 文档编写的 AI 技能，覆盖 OpenAPI 3.1/Swagger 规范、端点文档、认证流程、错误处理、版本控制与 SDK 指南全链路。
  • 核心能力：产出可直接被 Redoc、Swagger UI、Stoplight 渲染的规范文件，同时能写出开发者真正照着就能跑通的 curl 示例与错误码表。
  • 差异化：不止"写文档"，还强调技术准确性（$ref 复用、模式约束、全响应码覆盖）与技术写作可用性（先示例后解释、主动语态、故障排查提示）。
  • 适用人群：后端工程师、API 平台负责人、技术文档工程师、SDK 维护者、需要交付接口契约的研发团队。
  • 上手成本：无需学习新的语法体系，只要会描述你的接口，技能即可按 OpenAPI 结构组织输出，细节以官方说明为准。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：API文档编写Skill 技能英文名：api-documentation 技能ID：13526 解决的问题：接口写完了却没人愿意写文档；文档和代码对不上；认证、错误码、速率限制这些"关键但枯燥"的部分总是缺失；前端和第三方开发者反复追问同一个问题。这个技能把"写 API 文档"从一件靠自觉的苦差事，变成一次结构化、可复用、可交付的输出。

一键安装的思路

AI 技能的安装逻辑通常遵循"找到技能 → 安装到工作区 → 在对话中调用"三步：

  1. 安装前提：你使用的 AI 客户端或平台需要支持技能（Skill）机制，并且已登录可用的账号。具体支持的客户端版本与账号要求，以官方说明为准。
  2. 找到技能：在技能市场/技能列表中，通过技能名称 api-documentation、中文名「API文档编写」或技能 ID 13526 进行检索定位（检索入口与具体操作路径以官方说明为准）。
  3. 执行安装：点击安装/启用按钮，将技能加入当前工作区或项目。若平台支持命令行安装方式，命令格式请以官方文档给出的为准，不建议照搬非官方来源的指令。
  4. 验证是否生效：安装完成后，在对话中直接提出一个典型请求，例如"帮我为 POST /users 这个接口写一段 OpenAPI 3.1 规范，包含 201、400、409 三种响应"，如果返回结果具备规范的 openapi:、paths:、components: 层级结构，即说明技能已生效。

为什么"一键安装"能提升开发效率

传统做法是打开 Swagger Editor 手写 YAML，一边查语法一边猜团队约定。技能安装后，团队可以把"文档规范"沉淀成一次性的调用习惯：同一个技能产出的文档在字段命名、错误码格式、示例风格上天然一致，减少了大量评审和返工。

该技能的主要功能和特点

  • 完整 OpenAPI 3.1 规范输出：支持 JSON Schema 2020-12 词汇，可用 const、if/then/else、dependentSchemas，以及带鉴别器的 oneOf/anyOf/allOf。
  • 七大文档组件全覆盖：认证方式、基础 URL（多环境）、端点、模式（Schema）、错误码、速率限制、版本控制策略，一项不落。
  • 示例体系化管理：区分单一示例（example）与多场景示例（examples 命名对象），并在模式级与操作级都可挂载，方便文档工具直接渲染。
  • Webhook 与内容协商文档：支持 webhooks 段描述事件推送，支持 application/json、application/xml、text/csv 多内容类型并存。
  • 多种安全方案：OAuth2 多流程、OpenID Connect 发现、双向 TLS、基于扩展的自定义安全方案，配合 Bearer JWT 与 API Key 双认证的完整说明。
  • 错误处理标准化：统一的错误响应包结构（code / message / details / requestId），配套 HTTP 状态码对照表与常见错误代码速查表。
  • 版本控制与迁移指南：区分破坏性变更与非破坏性变更，给出 v1→v2 的并排迁移对比写法。
  • SDK/客户端文档：包含安装、快速开始、配置项、资源方法、错误类型（如 ValidationError、RateLimitError）与 TypeScript 类型支持说明。
  • 面向工具链友好：使用 operationId 保证客户端代码生成稳定，逻辑化 tags 便于导航，描述文本在 Markdown 与 UI 工具中都能良好渲染。

和普通文本生成工具比强在哪：普通工具能写"看起来像文档"的文字，但常常给不出可被工具消费的规范结构、写不全响应码、示例与模式对不上。这个技能把"技术准确性"作为硬约束——用 $ref 保持 DRY、示例必须与模式一致、所有可能的响应码都要覆盖。

如何使用该技能？

步骤一：先让技能"理解你的 API"

调用时先提供接口清单与背景，让技能建立上下文：

我有以下接口需要写文档：
- GET    /users          列出用户（分页）
- POST   /users          创建用户
- GET    /users/{userId} 按 ID 获取
- PATCH  /users/{userId} 更新
- DELETE /users/{userId} 删除
认证方式：Bearer JWT + X-API-Key 双方案
限制：标准 100 次/分钟，认证用户 1000 次/分钟

步骤二：指定输出格式

可以要求三种形态，按需组合：

  • OpenAPI 规范文件：用于导入 Swagger UI / Redoc / Stoplight。
  • Markdown 端点文档：用于 Wiki、GitHub README、内部知识库。
  • 专项章节：只写认证、只写错误处理、只写版本迁移。

步骤三：获取输出并核对

一份合格的输出通常长这样（节选自技能支持的结构）：

openapi: 3.1.0
info:
  title: 用户管理API
  version: 2.0.0
servers:
  - url: https://api.example.com/v2
    description: 生产环境
  - url: http://localhost:3000/v2
    description: 本地开发
paths:
  /users:
    get:
      summary: 列出所有用户
      operationId: listUsers
      tags: [用户]
      parameters:
        - $ref: "#/components/parameters/PageParam"

注意 operationId 与 tags 是关键字段：前者决定生成的 SDK 方法名，后者决定文档导航分组。

步骤四：补齐"开发者最容易踩坑"的部分

明确要求技能输出以下内容，效果最明显：

  • 每个端点的可工作 curl 示例（不是占位符）；
  • 具体数字的速率限制说明，含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 三个响应头；
  • 用完整可复制示例解释认证，含令牌生命周期表（访问令牌 1 小时、刷新令牌 30 天）；
  • 常见错误场景的字段级 details 数组示例。

步骤五：接入文档工具链

规范写好后即可生成交互式文档。技能覆盖的典型工具命令包括：

# 生成静态文档页面
npx @redocly/cli build-docs openapi.yaml --output docs.html

# 规范校验
npx @redocly/cli lint openapi.yaml

# 生成 TypeScript 客户端
openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

# 从规范启动 Mock 服务
prism mock openapi.yaml

各命令的参数与版本差异以对应工具的官方说明为准。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
API文档编写Skill（api-documentation） AI 驱动的 API 文档生产与规范编写技能 OpenAPI 3.1 规范、端点文档、认证、错误处理、版本控制、SDK 指南、Webhook 与内容协商 安装技能后以自然语言调用，无需额外学习 DSL 从零起草规范、补齐缺失章节、重构现有文档、生成迁移指南 优势：结构完整、示例与技术写作兼顾、支持多形态输出；不足：产出的规范仍需接入 Redoc/Swagger UI 等工具做渲染与校验
Swagger Editor（手写 YAML） 官方在线/离线规范编辑器 语法高亮、实时预览、基础校验 需熟悉 OpenAPI 语法，逐行手写 小型接口、快速原型验证 优势：所见即所得、社区认知度高；不足：认证流程、错误码表、迁移指南等长篇内容全靠人工，重复劳动多
Stoplight 平台 设计优先的 API 设计与文档平台 可视化建模、Mock、共享组件库、文档托管 需要团队采购与学习平台操作，成本较高 大型团队协作、设计先行工作流 优势：协作与治理能力强；不足：偏重平台化操作，文本创作环节仍需人写，轻量场景性价比低
通用 AI 助手直接生成 通用对话式文本生成 能输出 Markdown 或类 YAML 文本 零门槛，直接提问 临时性、非正式的接口说明 优势：上手最快；不足：容易漏响应码、示例与模式不一致、缺少 $ref 复用与 operationId 等工具链关键约定

选型建议：如果只是临时说明，通用 AI 够用；如果要交付可被工具消费、能被前端和第三方直接依赖的契约文档，专业技能的规范性优势明显；如果团队已有 Stoplight 类平台，可把技能当作"内容生产端"，平台作为"渲染与协作端"。

该技能的典型应用场景与实际体验情况

场景一：后端工程师交付新模块接口

角色与痛点：后端刚上线用户管理模块，被前端追着问"创建用户返回什么、密码规则是什么、邮箱重复报什么错"。 使用方式：把接口清单、认证机制、限流策略一次性描述给技能，要求输出 OpenAPI 3.1 规范 + Markdown 端点文档。 实际体验：输出中会主动补上 409 USER_EXISTS 这类"工程师容易忘了写"的响应码，并给出 VALIDATION_ERROR 带 details 字段级错误的示例。上手难度低，主要成本在于把自己的接口讲清楚。注意事项：示例中的邮箱、令牌等敏感数据需要替换为真实可用的测试数据。

场景二：技术文档工程师重构存量文档

角色与痛点：文档分散在多个 Wiki 页面，认证章节写在新人看不懂的位置，版本迁移记录缺失。 使用方式：按"渐进式披露"结构重排——认证快速开始（单一示例）→ 常见用例 → 完整端点参考 → 高级主题（Webhook、分页策略）。 实际体验：技能内置的结构化套路省去了重新设计目录的时间，版本控制章节还能直接产出破坏性/非破坏性变更清单与 v1→v2 并排迁移对比。注意事项：存量文档的业务背景知识仍需人工补充，技能负责结构与表达。

场景三：SDK 维护者编写客户端指南

角色与痛点：SDK 有安装说明但缺少完整的资源方法示例与错误类型说明，用户抱怨"不知道捕获哪种异常"。 使用方式：要求输出包含安装、快速开始、配置项（超时、重试、日志器）、资源方法（列表/获取/创建/更新/删除）与错误类型（ValidationError、RateLimitError、ApiError）的完整指南。 实际体验：能自动给出"限流错误时读取重试秒数并等待"这类实用处理范式，TypeScript 类型示例也可一并生成。注意事项：包名、命令需替换为你自己的真实发行包，具体版本号以官方发布为准。

场景四：平台团队治理 API 一致性

角色与痛点：多个团队各写各的文档，字段命名、错误格式、状态码用法五花八门。 使用方式：用技能统一生成规范模板，再配合 npx @redocly/cli lint 与 Spectral 自定义规则做 CI 卡口。 实际体验：统一的错误响应包结构（code/message/details/requestId）与统一的状态码对照表，让评审从"争论格式"转向"讨论设计"。注意事项：规则集需要团队自己维护，工具版本行为以官方说明为准。

该技能能为用户带来的价值

效率提升：一份覆盖端点、模式、认证、错误、限流的完整规范，人工手写往往需要数小时到数天；技能可在一次对话内产出初稿，工程师只需审校，把时间从"敲 YAML"转移到"确认业务语义"。

门槛降低：不熟悉 OpenAPI 3.1 的工程师也能拿到带 $ref 复用、带 operationId、带多场景 examples 的规范文件；不擅长写作的后端也能产出结构清晰、主动语态、先示例后解释的文档。

协作收益：前端、第三方开发者、SDK 维护者拿到的是同一份真相源。认证怎么传、限流多少、错了看哪个字段，都有具体答案，显著减少重复答疑。

长期价值：规范文件可直接驱动客户端代码生成、Mock 服务与契约测试，文档从"事后补的说明"变成"参与研发流程的契约资产"。版本控制与迁移指南的沉淀，则让 API 的演进有据可依——提前公告弃用、并排展示变更、维护带标签的变更日志。

常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ A：在支持技能机制的 AI 平台中，通过技能名 api-documentation、中文名「API文档编写」或技能 ID 13526 检索并安装即可。具体安装入口、是否收费、是否包含试用额度，均以官方说明为准，不同平台可能不同。

Q2：安装后怎么确认它真的生效了？ A：给它一个具体任务，例如"为 POST /users 写 OpenAPI 3.1 片段，覆盖 201/400/409 响应"。如果返回内容包含 openapi:、paths:、components/schemas 层级，且响应码与示例齐全，说明技能已正常工作。

Q3：它产出的规范能直接导入 Swagger UI 或 Redoc 吗？ A：技能按 OpenAPI 3.1 结构与 JSON Schema 2020-12 词汇输出，设计目标就是供 Redoc、Swagger UI、Stoplight 等工具自动生成交互式文档。实际导入前建议先跑一次 npx @redocly/cli lint openapi.yaml 做校验，工具版本差异以官方说明为准。

Q4：它适合谁用？不适合谁用？ A：适合需要交付可被工具消费的契约文档的后端工程师、文档工程师、SDK 维护者和 API 平台团队。如果只是写一段临时说明，或团队完全没有 REST API 场景（例如纯内部脚本），收益有限。

Q5：和 Stoplight、Swagger Editor 这类工具是替代关系吗？ A：不是替代，而是分工。技能负责"把内容写对写好"，工具负责"渲染、校验、协作与托管"。推荐组合是：技能生产规范与文档内容，Swagger UI / Redoc / Stoplight 负责展示与治理，OpenAPI Generator、Prism、Dredd 负责下游的代码生成、Mock 与契约测试。