上个月接手一个老项目，接口文档早就和代码脱节了——前端拿着过时的API文档联调，三天两头出问题。我花了一周时间手动补文档，补到怀疑人生。后来想，能不能让GPT-4来干这活？试了两周，还真跑通了。现在每次提交代码，CI自动生成最新接口文档，人工只需要复核。整个过程分享出来，踩过的坑也一并说了。

目标：从代码到文档，全自动

项目是Spring Boot + Swagger注解，但很多老接口没写注解，或者注解信息不完整。目标是：解析Controller代码和Swagger注解，生成结构清晰的Markdown接口文档，包含接口路径、方法、参数、返回示例，并自动接入GitLab CI。人工只需要在合并请求时检查差异。

环境准备

  • Python 3.9+，用FastAPI写了个小服务，封装GPT-4调用
  • Java项目使用Maven，Swagger依赖已存在
  • GitLab CI，Runner已配置
  • OpenAI API Key，注意用量控制

步骤1：抽取代码上下文

直接用整个项目文件喂给GPT-4不现实，token消耗大，响应还慢。我写了个Python脚本，用正则和简单AST解析，提取每个Controller类的方法签名、注解和Javadoc。对于Swagger注解，优先提取@ApiOperation的value和notes。

import re from pathlib import Path def extract_controllers(project_root): controllers = [] for path in Path(project_root).rglob('*Controller.java'): content = path.read_text(encoding='utf-8') # 提取类名和方法 class_match = re.search(r'class\s+(\w+)', content) if not class_match: continue class_name = class_match.group(1) methods = re.findall(r'@(Get|Post|Put|Delete)Mapping\("([^"]+)"\)\s+public\s+(\w+)\s+(\w+)\(([^)]*)\)', content) controllers.append({'class': class_name, 'methods': methods}) return controllers

对于没有注解的接口，只能靠方法名和参数名猜，这部分后面交给GPT-4补全。

步骤2：设计提示词

提示词是整个流程的核心。我试过几个版本，最有效的结构是：角色设定 + 输入数据 + 输出格式要求 + 约束条件。让GPT-4扮演技术文档工程师，输入代码片段，输出Markdown表格。

system_prompt = """你是一名资深后端工程师，擅长编写API文档。根据提供的Java Controller代码和Swagger注解，生成规范的Markdown接口文档。要求： 1. 每个接口包含：路径、方法、描述、请求参数（名称、类型、必填、说明）、返回示例（JSON格式，合理构造） 2. 如果代码中没有说明，根据方法名和参数名推断功能，并标注“推断” 3. 对于缺失的信息，用“待补充”标出 4. 输出严格按以下Markdown格式： ### 接口名称 - 路径： - 方法： - 描述： - 请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| - 返回示例： ```json {...} ``` """

把代码片段拼到user消息里，控制每次请求的方法数量在5-10个，避免输出过长被截断。

步骤3：调用GPT-4生成文档

用OpenAI的聊天补全接口，设置temperature=0.2，保证输出稳定。我封装了重试机制，遇到网络错误自动重试。

import openai def generate_doc(code_snippet): response = openai.ChatCompletion.create( model='gpt-4', temperature=0.2, messages=[ {'role': 'system', 'content': system_prompt}, {'role': 'user', 'content': f'请生成以下接口的文档：\n```java\n{code_snippet}\n```'} ] ) return response.choices[0].message.content

第一次跑完，发现返回示例经常是空对象，或者参数说明太泛。后来在提示词里加了“根据业务语义构造合理示例”，效果好了很多。

步骤4：解析和合并文档

GPT-4输出的Markdown需要清洗和合并。我写了正则提取每个接口块，按路径排序，再插入到总文档的对应位置。同时，用git diff对比旧的文档，自动标记变更。

import re def parse_markdown(md): pattern = r'### (.+?)\n- 路径：(.+?)\n- 方法：(.+?)\n- 描述：(.+?)\n- 请求参数：\n((?:\|.*?\n)+)- 返回示例：\n```json\n(.*?)\n```' matches = re.findall(pattern, md, re.DOTALL) return [{'name': m[0], 'path': m[1], 'method': m[2], 'desc': m[3], 'params': m[4], 'resp': m[5]} for m in matches]

这一步容易出问题：GPT-4偶尔会漏掉字段或格式不完整，所以必须做校验，不完整的重新生成一次。

步骤5：集成到GitLab CI

在.gitlab-ci.yml里加一个job，每次main分支有提交时运行。脚本拉取代码、执行Python生成文档，然后提交回仓库。

doc-generation: stage: test script: - python generate_docs.py - git add api-docs.md - git commit -m "docs: update API docs" || echo "No changes" - git push only: - main

这里有个坑：CI要有权限推代码，我用的是个人access token，注意保密。另一个坑是循环触发——推送文档又触发CI，所以只对docs目录的变更忽略。

常见问题

  • token消耗大：每次全量生成太贵。我改成只针对变更的文件生成，用git diff来定位。
  • GPT-4输出不稳定：同一个接口生成两次，可能不一样。解决方案是temperature调低，并增加格式校验，不合格重试。
  • 老接口没注解：这类接口描述全靠猜，容易错。我让GPT-4标注“推断”，人工复核时重点看。
  • CI权限问题：用project access token比个人token更安全。
核心收获：GPT-4不是全自动替你写文档，而是把80%的重复劳动自动化，剩下20%的语义判断交给人工。关键是提示词和校验要设计好，否则生成一堆废话。

总结

这个流程跑了一个月，接口文档的时效性从“永远滞后”变成“提交即更新”，前端同事再也没抱怨过文档不对。当然，GPT-4不是万能的，复杂业务逻辑的描述还是需要人工调整。但作为技术负责人，我觉得这钱花得值——省下的时间足够做更多有价值的事。如果你也想在项目里落地类似的自动化，不妨从一个小模块开始试。我们团队最近也在用AI优化开发流程，比如时光智行小程序的文档生成，就是类似的做法。