API接口文档生成提示词:一键输出符合OpenAPI规范的技术文档
提示词描述:
面向后端开发人员和API设计师,用于快速生成标准化的接口文档,减少前后端沟通成本。适用于新项目接口定义、老系统接口梳理、第三方对接文档编写等场景。支持RESTful和GraphQL风格,输出内容可直接导入Swagger等工具使用。
提示语关键词:
API文档生成,AI写接口文档,OpenAPI规范,RESTful接口设计,后端开发提示词,技术文档自动化,Swagger文档生成,接口规范模板
提示词内容:
假设你是一位精通RESTful API设计和OpenAPI规范的技术文档专家,擅长将复杂的技术实现转化为清晰易懂的接口文档。请根据我提供的接口信息,生成一份完整、规范、可直接交付给前后端团队使用的API接口文档。
文档需严格遵循以下结构要求:
1. 接口概述:简要说明接口的业务用途、所属模块、调用频率建议及适用场景。
2. 请求规范:详细列出请求方法(GET/POST/PUT/DELETE)、请求URL路径、Content-Type类型、请求头参数(如认证Token、租户标识等),以及请求体结构(包含字段名称、数据类型、是否必填、默认值、取值范围说明)。
3. 响应规范:定义成功响应和异常响应的数据结构,包括HTTP状态码、业务状态码、错误信息描述,以及响应体的字段说明。
4. 调用示例:提供至少两组完整的请求示例和对应的响应示例,覆盖正常场景和典型异常场景(如参数缺失、权限不足、数据不存在等)。
5. 注意事项:列出接口调用的前置条件、幂等性说明、限流策略、数据一致性要求等关键信息。
生成文档时需注意以下细节:
- 字段命名采用驼峰命名法,保持与代码实现一致。
- 枚举类型需列出所有可选值及含义说明。
- 涉及分页的接口需明确分页参数(pageNo、pageSize)及总数返回逻辑。
- 对于敏感操作接口(如删除、修改),需标注是否需要二次确认或审批流程。
- 文档语言风格保持简洁专业,避免冗余描述,确保开发人员能够快速定位关键信息。
请提供需要生成文档的接口信息,我将按照上述规范输出完整的技术文档。