用途:为 RESTful API 提供设计与文档规范,帮助开发者按行业标准编写接口说明。
主要能力:要求使用 OpenAPI 3.0+ 描述 API,示例包含 info、paths、components 等结构,用 $ref 复用 schema;给出 REST 约定,包括用名词命名资源(如 /users、/orders)、正确使用 GET、POST、PUT、PATCH、DELETE、返回合适状态码(200、201、400、404、500)、列表分页(?page=1&limit=20)以及 API 版本化(/v1/users)。同时提供统一错误响应格式,含 error.code、error.message 与 details 字段列表。
使用方式:按资料中的 OpenAPI 片段组织接口文档,并遵循所列 REST 约定与错误结构。资料未提供安装命令或具体调用步骤。
适用场景:需要编写或评审 REST API 文档、统一接口风格与错误返回的团队。
限制:资料仅覆盖 OpenAPI 3.0+ 与 REST 约定,未涉及认证、限流、GraphQL 等主题;未提供收费、平台或效果信息。