用途:帮助编写开发者友好的 API 文档,覆盖 OpenAPI/Swagger 规范、端点参考、认证指南、多语言代码示例与开发者体验实践。
主要能力:以“清晰、完整、同步”为原则,指导记录所有公开端点、请求/响应示例、错误码及修复步骤,并提供多语言代码示例;不记录内部/私有端点,不假设读者了解业务领域,不让文档与实现脱节。
使用方式:以 OpenAPI 3.1.0 的 openapi.yaml 为骨架,包含 info、servers、tags、paths、components 等部分;在 paths 中按 operationId、summary、description、parameters、requestBody、responses 描述端点;在 components 中定义 schemas、securitySchemes、responses 等可复用对象。认证部分支持 BearerAuth(JWT)与 ApiKeyAuth(X-API-Key),并说明令牌过期与刷新。错误文档统一为 error.code、error.message、error.details 结构,并按认证、校验、资源、限流分类列出 HTTP 状态与解决方式。变更日志按 Added、Changed、Deprecated、Fixed、Security 分组。交互式文档部分提及 Swagger UI 配置,但资料中该段内容不完整。
适用场景:需要为公开 API 编写规范、端点参考、认证说明、错误码表、变更日志与多语言示例的团队。
限制:资料未提供安装命令、收费、价格、平台支持或具体效果数据;部分示例(如 Swagger UI 配置)内容不完整,暂未提供完整细节。