CodeGeeX接口文档生成操作指南

从事 API 开发的人员都清楚，编写文档是一件极为繁琐的工作——代码逻辑已经调试通过，却仍需回头补充参数说明、请求体示例、状态码映射，更令人困扰的是文档与代码时常不同步，一旦修改逻辑便需手动逐一核对。CodeGeeX 提供了一套实用的解决方案，涵盖从单文件到跨模块再到项目级文档的完整场景，共三种方式。

设想这样一个场景：你刚刚完成一批 Python 或 TypeScript 的 HTTP 接口函数，需要快速生成结构统一、字段准确、可直接用于 Swagger UI 渲染的 API 文档。手动补充？速度太慢。复制粘贴？容易出错。最理想的方式是让工具自动理解代码，生成的内容与当前代码逻辑严格一致，且参数说明、示例 JSON、状态码映射一应俱全。

用快捷键批量生成单文件内所有函数文档

如果你已经编写完核心接口函数，但整个文件中没有任何文档字符串，这是最便捷的方法。一次触发，即可扫描当前打开文件中所有可识别的函数。

操作非常简单：将光标放置在任意一个待文档化函数名称的左侧空白处（注意不要选中任何文本），然后按下 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（Mac）。CodeGeeX 会自动扫描文件中所有符合签名规范的函数，逐个在它们上方插入 Markdown 风格的文档字符串，使用 """ 包裹。如果某个函数已存在文档字符串，则默认跳过，不会覆盖你手写的内容。

生成完成后请检查：文档字符串中是否包含请求体的示例 JSON 和状态码映射表？如果缺失，通常是因为函数缺少类型注解，或者未使用 Pydantic/BaseModel 定义数据结构。补充这些信息后再次尝试即可。

通过侧边栏问答提取跨文件 API 元数据

当项目分散在多个文件中（例如 routes/、controllers/），且部分函数连类型提示都没有时，上述快捷键方式将不再适用——因为静态解析无法理解语义。此时需要换一种思路：直接让模型理解代码的上下文。

方法一：自然语言提问 + 批量代码拖入

首先点击 VS Code 左侧活动栏中的 CodeGeeX 图标，打开侧边栏面板。然后输入问题，例如：“请从以下 Flask 路由代码中提取全部 GET/POST 接口，生成 OpenAPI v3.0.3 YAML 格式文档，包含 path、method、summary、requestBody schema（含 required 字段）、responses 200/400 描述”。接着，按住 Ctrl（Windows/Linux）或 Cmd（Mac），在编辑器中框选多个路由函数，右键选择“Copy as Plain Text”，粘贴到侧边栏输入框底部，按回车键即可。

方法二：上传压缩包解析整个模块

如果文件过多，逐个复制较为繁琐，可以直接将整个路由目录打包成 zip 文件上传。点击侧边栏右上角的“ 附加文件”按钮，选择包含 __init__.py 的完整路由目录压缩包，剩余工作交给模型。

用 CLI 工具生成含接口概览表的 README.md

当项目已完成多模块开发，需要对外交付项目级文档时，使用 CLI 工具生成一份带表格索引的 README.md 是最佳选择。该工具能自动扫描所有接口文件，提取路径、方法、摘要、参数数量，生成一个带超链接的概览表，用户点击即可跳转到对应代码段。

操作步骤如下：

第一步：确保已安装 CodeGeeX CLI 工具。Python 环境执行 pip install codegeex-cli，Node 环境执行 npm install -g codegeex-cli。

第二步：进入项目根目录，运行命令：codegeex readme --input src/ --output docs/README.md --title "My API Service"。

第三步：CLI 自动扫描所有 Python/TypeScript 接口文件，提取路径、方法、摘要与参数数量，生成带超链接的接口概览表。

第四步：打开生成的 docs/README.md，确认表格中每行对应一个真实接口。这里有一个关键点需要特别注意：表格中的 path 字段必须与实际路由装饰器完全一致，否则链接跳转会失效。