如何用Kimi自动化生成API接口文档_采用Swagger格式提示词-人工智能-PHP中文网

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

可利用kimi将非结构化接口说明、curl命令或postman集合转化为符合openapi 3.0规范的swagger yaml/json文档：一、基于文本描述生成，需提供路径、方法、参数等完整信息；二、从curl命令反向推导，自动识别url、headers、body结构；三、解析postman集合json，提取请求与响应细节并生成带正则约束的schema。

如果您拥有已部署的api服务但缺乏结构化文档，且希望借助kimi快速产出符合swagger规范的接口描述，则可利用其对openapi语义的强理解能力直接生成可落地的yaml或json格式定义。以下是实现该目标的可行方法：

一、基于原始接口说明文本生成Swagger定义

该方法适用于仅有自然语言描述（如Word、Markdown或邮件中的接口说明）而无代码或注释的场景。Kimi能将非结构化文本解析为字段级参数、状态码、请求/响应体结构，并映射至OpenAPI 3.0核心字段。

1、整理待文档化的接口信息，确保包含：接口路径、HTTP方法、请求头要求、请求参数（位置、类型、是否必填）、成功响应示例、常见错误码及含义。

2、向Kimi发送如下提示词：请根据以下接口描述，生成标准OpenAPI 3.0 YAML格式定义。要求：paths节点中每个接口必须包含summary、description、parameters（按query/path/body分类）、requestBody（含application/json schema）、responses（含200及至少两个4xx/5xx状态码，每个response需含description和content.application/json.schema）、components.schemas中定义所有引用的请求/响应对象，所有字符串字段标注maxLength，数值字段标注minimum/maximum，枚举值用enum列出。

3、将接口描述粘贴在提示词之后，提交请求。

4、检查Kimi输出中paths下的operationId是否唯一、schema中required数组是否与必填参数完全一致、所有$ref引用是否在components下存在对应定义。

二、依据已有curl命令反向推导Swagger片段

该方法适用于仅有测试用curl命令、无其他上下文的情况。Kimi可通过解析curl参数自动识别URL、method、headers、body结构及参数来源，进而构建OpenAPI基础骨架。

1、准备一条完整可执行的curl命令，例如：curl -X POST "https://api.example.com/v1/orders" -H "Authorization: Bearer ${token}" -H "Content-Type: application/json" -d '{"product_id":101,"quantity":2}'。

2、向Kimi发送提示词：请将以下curl命令转换为OpenAPI 3.0 YAML格式的单个paths条目。要求：从curl中准确提取HTTP方法、完整URL路径、所有-H头字段（转为parameters或securitySchemes）、-d参数内容（转为requestBody.application/json.schema，推断各字段类型与约束），并在responses中为201状态码生成含id和created_at字段的JSON schema。

3、粘贴curl命令，提交请求。

Kimi Search

使用 Moonshot Kimi API 的 $web_search 内置工具进行联网搜索。当需要进行网络搜索获取实时信息时使用，支持中文和英文搜索查询。需要配置 MOONSHOT_API_KEY。

下载

4、验证生成结果中securitySchemes是否正确定义BearerAuth、paths下security字段是否引用该方案、requestBody.schema是否将product_id识别为integer类型且quantity标注minimum: 1。

三、从Postman集合导出数据生成Swagger文档

该方法适用于团队已在Postman中维护接口集合的情形。Kimi可解析Postman导出的JSON文件，提取请求结构、示例、测试脚本中的断言逻辑，并转化为OpenAPI可执行描述。

1、在Postman中选中目标集合，点击「Export」→「Collection v2.1」，保存为JSON文件。

2、打开该JSON文件，复制顶层"item"数组中一个典型请求对象的全部内容（含name、request、response）。

3、向Kimi发送提示词：请将以下Postman请求对象转换为OpenAPI 3.0 YAML格式的paths条目。要求：使用请求name作为summary，从request.url.raw提取path和variables，从request.method获取HTTP方法，从request.header解析认证头并映射到securitySchemes，从request.body.raw提取JSON结构并生成requestBody.schema，从response[0].code和response[0].body推导200响应schema，所有字符串字段添加pattern正则约束（如email字段用^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$）。

4、粘贴Postman请求对象JSON，提交请求。

5、核对生成内容中path变量是否转为OpenAPI path parameter、response body是否保留原始字段顺序、pattern正则是否符合RFC 5322邮箱格式。