在现代开发过程中，API 文档的生成和维护是一项重要且重复的工作。传统的手动方式耗时且容易出错，而借助 AI 技术，我们可以大大提升文档生成的效率。本文将介绍如何使用 AI 生成 YAPI 接口文档，简化开发者的工作流程。

yapi 简介

API 文档是前后端团队协作的重要桥梁。完整、准确的接口文档可以提高开发效率，减少沟通成本。
YAPI 是一款常用的 API 管理工具，允许开发者集中管理 API 接口文档，并提供强大的 API 测试和团队协作功能。

根据接口参数生成文档

根据接口参数范例生成yapi接口文档，非常简单，只需要制定简单的提示词。如：

下面是接口查询响应示例，字段都必填。
字段的示例值追加到 description 列中，
请生成 yapi 的 JSON-SCHEMA，方便我直接导入到 yaip 中。
[接口查询响应示例]

这个生成的内容就可以直接导入到yapi中了。

根据接口代码生成文档

AI根据接口代码生成接口文档的核心在于通过解析代码自动提取接口定义信息。主要包括的流程：
1、代码解析：AI通过解析项目中的代码，识别出API接口、请求方式（如 GET、POST）、请求参数、返回类型等。
2、接口注释分析：如果项目中有注释，AI可以根据这些注释补充接口描述、参数说明等细节，生成更完善的文档。
3、数据结构识别：AI自动分析代码中的数据结构（如DTO、实体类），并将其映射到接口的请求和响应体中。
4、自动上传至yapi：生成完接口数据后，利用yapi提供的接口将文档自动上传到yapi平台。注：yapi提供了灵活的api，允许开发者批量导入接口文档。

下面是一个简单例子：

@RestController
@RequestMapping("/api/orders")
public class OrderController {
    @PostMapping("/create")
    public ResponseEntity<OrderRespDTO> createOrder(@RequestBody OrderReqDTO orderReq) {
        // 创建订单逻辑 ...
        return ResponseEntity.ok(new OrderRespDTO());
    }
}

通过代码解析，AI 可以提取以下信息：

• 请求路径：/api/orders/create
• 请求方式：POST
• 请求参数：OrderReqDTO
• 返回类型：OrderRespDTO

然后通过代码，将数据上传到yapi平台，以JavaScript代码为例：

fetch('https://yapi.example.com/api/interface/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        "token": "your_project_token",
        "title": "Create Order API",
        "path": "/api/orders/create",
        "method": "POST",
        "params": [{"name": "orderReqDTO", "type": "OrderReqDTO"}],
        "response": {"type": "OrderRespDTO"}
    })
})

总结

使用AI生成YAPI接口文档是提升开发效率的一种有效方式。通过自动化工具，我们开发人员能够将更多时间集中在核心业务上，减少繁琐的文档编写工作。