不手写 API 文档：用 Trae Agent 从 docstring 一路生成 OpenAPI

不手写 API 文档用 Trae Agent 从 docstring 一路生成 OpenAPI【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent发版前好几个接口的入参改了名字README 里的示例却还停在上个迭代——你大概也遇过这种代码和文档各过各的局面。Trae Agent 的文档生成工具链就是冲着这件事来的用 LLM 把 docstring 变成 OpenAPI让 API 文档跟着代码走而不是追着代码改。先看到结果一条命令生成 OpenAPI 文档先别关心内部机制跑一条命令看产出trae run 扫描 src/api/users.py 的 docstring生成 /docs/api_spec.jsonOpenAPI 3.0 \ --working-dir /path/to/your/repo30 秒后你会在docs/下拿到类似这样的骨架{ openapi: 3.0.0, info: { title: Users API, version: 1.0.0 }, paths: { /users: { post: { summary: 创建新用户, operationId: create_user } } } }一句话能生成带paths的 OpenAPI 骨架这就是它想替你干的活。分清两个编辑工具怎么分工 工具能干活靠的是底下两个编辑引擎。理解它们的差别就看一句类比str_replace_based_edit_tool像拿着唯一锚点做外科手术你给一段确定能精确命中的原文old_str它原样换掉json_edit_tool则像对着结构图JSONPath往节点里塞数据、删节点。前者管纯文本——Markdown、HTML、代码文件都归它定位靠多行精确匹配old_str必须在整份文件里唯一否则它宁可不改。它暴露了view、create、str_replace、insert几个子命令还有个view_range能按行号区间看文件适合排错。后者只管 JSON靠 JSONPath 表达式定位$.paths[/users].post、$..key这种写法都支持操作是view、set、add、remove。改 OpenAPI 规范、配置文件这种结构化东西用它比整段文本替换稳得多。一句话概括两者边界见下维度str_replace_based_edit_tooljson_edit_tool处理对象纯文本Markdown/HTML/代码JSON 结构化文件定位方式多行精确匹配old_str须唯一JSONPath 表达式主要操作view / create / str_replace / insertview / set / add / remove想细看这两个工具的定义可以翻 trae_agent/tools/ 下的edit_tool.py和json_edit_tool.py。跑通从 docstring 生成 OpenAPI上面那条命令背后其实是三段接力。源头是一份符合 Google 风格的 docstringdef create_user(username: str, email: str) - dict: 创建新用户 Args: username: 用户登录名4-20 个字符 email: 用户邮箱需符合 RFC 5322 Returns: dict: 含 user_id 与 created_at Raises: ValueError: 用户名已存在或邮箱格式非法 Agent 先把这份注释解析成 OpenAPI 的字段再用json_edit_tool落一个空骨架trae run 用 json_edit_tool 在 /docs/api_spec.json 建 OpenAPI 3.0 骨架含 info 和空 paths骨架就位后往具体节点里填内容就交给 JSONPath 的addtrae run 用 json_edit_tool 对 /docs/api_spec.json 执行 addjson_path 为 $.paths[/users].post写入 summary、parameters、responses填充的 value 大致长这样{ summary: 创建新用户, parameters: [ { name: username, in: query, required: true, schema: { type: string } } ], responses: { 200: { description: 用户创建成功 } } }从注释到骨架再到填值整条链不用你手动拼 JSON这也是 docs/tools.md 里两个工具配合的典型用法。让文档和代码不再各过各的改完接口文档还没同步这正是下面这套标记机制要解决的。它把多版本共存和代码示例自动刷新合并成一条工作流。版本层面用注释标记给文档分区!-- VERSION: 2.0 -- ## 快速开始 安装命令pip install trae-agent2.0之后只要说把VERSION: 2.0那段安装命令换成2.1工具就会定位到那个标记区做替换别的版本不动。代码示例层面用SNIPPET标记把文档块和真实文件绑起来!-- SNIPPET: examples/create_user.py --一旦examples/create_user.py变了监听端就会比对指纹发现不一致再回头刷新文档里对应的代码块流程如下版本标记管哪段正文SNIPPET 管哪块代码两个加起来正文和示例都能自动跟上源码。接进 CI文档维护就不用盯了 ⚡本地跑通之后最后一步是让它自己转。把文档生成挂进 GitHub Actions每次 push 自动更新name: 文档自动生成 on: [push] jobs: generate-docs: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: pip install . - run: trae run 从 trae_agent/cli.py 提取命令参数更新 /docs/cli_reference.md - uses: stefanzweifel/git-auto-commit-actionv5 with: commit_message: docs: 自动更新 API 文档 file_pattern: docs/*.md这样 docs/ 下的文档就是代码即文档的 CI 产物不用人盯。批量编辑难免翻车所以工具链带事务回滚改完先校验校验不过就整批回滚。核心就这几行try: edit_tool.str_replace(path/docs/guide.md, old_str旧内容, new_str新内容) if not validate_docs(): raise ValidationError(文档校验失败) edit_tool.commit_transaction() except ValidationError: edit_tool.rollback_transaction()校验这一步能挡住大部分把格式改坏的操作配合上面的自动提交就是文档维护流水线的闭环。让大文档不卡、格式不崩 大文件怎么处理看规模分档如果文档小于 100KB直接全量加载内存占用很小。如果在 100KB 到 1MB 之间按章节分块处理。如果超过 1MB走流式避免一次性吃进内存。对应到排查动作几条经验格式乱了先用view配view_range把行号框出来比如[15, 20]看清再改。出现重复段落用str_replace匹配去重标记删掉。版本冲突时给对应区域上锁再单独处理别整份重写。原文给出的数据是文档维护成本能降 72%我自己的体感是省了差不多七成时间。还能往哪些方向玩这条链子现在还能往几个方向长结合图像描述自动补流程图和架构图、基于文档内容搭 RAG 问答、以及多语言翻译并保持术语一致。这些还在路上不必现在就上。现在就接上把仓库拉下来装上跑一条trae run试试git clone https://gitcode.com/gh_mirrors/tr/trae-agent cd trae-agent pip install .【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考