系列文章程序员 AI 效率笔记 | 第五篇接口文档是前后端协作的基础但大多数程序员不爱写。接口改了文档忘更新字段描述要么没有要么过时新人来了只能看代码猜接口含义。AI 可以帮程序员根据代码快速生成接口文档、补全字段说明、统一格式让写文档这件事从负担变成顺手的事。为什么接口文档总是缺失或过时接口文档的重要性不需要解释但现实中大多数项目的接口文档要么不全要么是过时的。原因通常有几个写代码的时候功能还在变文档写早了要反复改功能做完了赶着上线文档往后排就再也没补接口一改代码更新了但文档没人跟着更新Swagger 注解写起来啰嗦很多人懒得写全字段描述要写中文代码里全是英文两边对不上结果就是前端靠 Postman 自己试新人靠问老人接口文档变成了摆设。AI 适合帮你做哪些接口文档工作1. 根据 Controller 代码生成接口描述你把接口代码发给 AI它可以提取路径、请求方式、参数、返回值生成结构化的接口文档。2. 补全字段中文说明代码里的字段名是英文AI 可以根据上下文推断含义并补上中文描述。3. 生成请求和响应示例AI 可以根据参数类型和业务场景生成合理的请求和响应 JSON 示例。4. 统一文档格式不同人写的文档格式不一样AI 可以帮你统一成固定模板。5. 根据接口变更生成更新说明把新旧代码对比发给 AI让它总结接口变更内容直接作为更新日志。实际操作从代码到接口文档第一步把接口代码发给 AI生成基础文档最简单的做法是把 Controller 方法代码直接发给 AI。比如你有一个查询订单列表的接口GetMapping(/api/orders) public PageResultOrderVO listOrders( RequestParam(required false) String status, RequestParam(defaultValue 1) int page, RequestParam(defaultValue 20) int pageSize) { return orderService.listOrders(status, page, pageSize); }提示词请根据下面的 Spring Boot 接口代码生成接口文档。 要求包含接口路径、请求方式、参数说明含是否必填和默认值、返回值结构、字段中文描述。 格式用 Markdown 表格。AI 会生成类似这样的文档### 查询订单列表 ​ - 路径GET /api/orders - 描述分页查询订单列表支持按状态筛选 ​ **请求参数** ​ | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | status | String | 否 | - | 订单状态筛选 | | page | int | 否 | 1 | 页码 | | pageSize | int | 否 | 20 | 每页条数 |你只需要检查字段描述是否准确补充 AI 猜不到的业务含义。第二步让 AI 补全字段的中文描述把 VO 代码发给 AIpublic class OrderVO { private String orderId; private String userId; private BigDecimal totalAmount; private String status; private LocalDateTime createTime; private LocalDateTime payTime; private String remark; }提示词请为下面 Java 类的每个字段补充中文描述格式用注释形式写在字段上方。 如果字段含义不确定标注待确认。对于含义模糊的字段比如 status 的枚举值AI 会标注出来提醒你补充。第三步生成请求和响应 JSON 示例提示词根据上面的接口文档生成一个完整的请求示例和成功响应示例。 请求参数用实际业务场景的值不要用 test、123 这种占位数据。 响应示例包含 2-3 条数据。AI 会生成贴近真实业务的 JSON 示例比你自己编数据快得多。第四步批量处理多个接口如果你有一整个 Controller 文件需要生成文档可以一次性发给 AI下面是一个完整的 OrderController包含 5 个接口。 请为每个接口生成文档格式统一包含路径、方式、参数表、返回值表、请求示例、响应示例。 接口之间用二级标题分隔。对于大型项目可以按模块分批生成最后合并成完整的接口文档。第五步让 AI 生成 Swagger 注解如果你的项目用 Swagger/OpenAPI手写注解很繁琐。可以让 AI 帮你补全请为下面的接口方法添加 Swagger 3OpenAPI注解。 包含 Operation、Parameter、Schema 注解description 用中文。AI 会在你的代码上补全注解你只需要复制回去。检查 AI 生成的文档重点看这几个地方字段含义是否准确AI 根据字段名推断含义但 status 的枚举值、amount 含税与否它不知道敏感信息代码如果涉及内部域名、密钥、真实用户数据发给 AI 之前要先脱敏文档和代码同步AI 帮你降低了写文档的成本但更新文档还是需要人去触发格式统一先定好模板再让 AI 按模板填充效果更好总结程序员用 AI 写接口文档最大的价值是把写文档从一件需要额外安排时间的工作变成写完代码顺手就能做的事。合理的分工是AI 负责提取接口结构、生成格式统一的文档和示例程序员负责确认业务含义和补充 AI 猜不到的细节。只要把代码写完→发给 AI 生成文档→人工过一遍这个流程跑顺接口文档就不再是负担了。#AI编程助手# #接口文档# #SpringBoot# #Swagger# #程序员效率#