SuperAPI AI 工具集

api-documentation-writer

编程与开发

查看项目

更新于 10-15 23:33

技能介绍

用途:帮助编写开发者友好的 API 文档,覆盖 OpenAPI/Swagger 规范、端点参考、认证指南、多语言代码示例与开发者体验实践。

主要能力:

  • 文档原则:清晰、完整、最新(与 API 实际行为同步)。
  • 记录范围:所有公开端点、各场景请求/响应示例、带修复步骤的错误码、主流语言代码示例;不记录内部/私有端点,不假设读者了解业务领域,不让文档与实现脱节。
  • OpenAPI 3.1.0 结构:info(标题、版本、描述、联系方式、许可证)、servers(生产/预发)、tags、paths、operationId、参数(分页、过滤、枚举、默认值)、响应(200/201/400/401/403/404/409/429)、components/schemas、securitySchemes(BearerAuth JWT、ApiKeyAuth)、可复用 responses。
  • 认证文档:Bearer JWT 与 X-API-Key 的获取与请求头写法,令牌过期与刷新说明。
  • Markdown 端点参考模板:端点、认证、请求体表格、curl 示例、成功与错误响应、错误码表。
  • 多语言示例:cURL、JavaScript(fetch/axios)、Python、Ruby、Go。
  • 错误文档:统一错误格式与认证、校验、资源、限流错误码及解决方式。
  • 变更日志:Added/Changed/Deprecated/Fixed/Security 分类格式。
  • 交互式文档:Swagger UI 配置(customCss 等)。

使用方式:按资料中的 OpenAPI YAML 与 Markdown 模板组织内容,保持命令与代码原样。

适用场景:为 REST API 编写规范、端点参考、认证与错误说明、变更日志及交互式文档。

限制:资料未提供安装命令、收费、价格、平台支持与效果数据,暂未提供。