用途:帮助编写开发者友好的 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 编写规范、端点参考、认证与错误说明、变更日志及交互式文档。
限制:资料未提供安装命令、收费、价格、平台支持与效果数据,暂未提供。