CodeGeeX生成API文档需绑定上下文、补全参数、识别注释：一、用内置功能（Ctrl+Shift+D）基于类型与注释生成Markdown；二、侧边栏问答提取元数据；三、配置本地LLM注入模板；四、遵循JSDoc/Pydoc规范；五、CLI批量导出项目级OpenAPI。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您使用CodeGeeX生成代码后，需要快速产出规范、准确的API文档，但发现文档内容缺失、格式混乱或与实际接口不一致，则可能是由于文档生成未绑定上下文、参数提取不全或注释未被识别。以下是实现从代码到文档无缝衔接的具体操作路径：
一、利用CodeGeeX内置文档生成功能
CodeGeeX支持基于函数签名、类型注解及自然语言注释自动推导API结构与说明，无需额外插件即可在IDE中触发文档生成。该方法依赖于代码中已存在的语义信息，适用于Python、TypeScript、Java等具备强类型或标准docstring风格的语言。
1、将光标置于待生成文档的函数名或类定义行首。
2、按下快捷键 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（Mac），触发“生成文档”指令。
3、CodeGeeX自动分析参数类型、返回值、异常声明及已有注释，插入符合OpenAPI 3.0基础结构的Markdown格式文档块。
4、检查生成内容中 path、method、requestBody schema、responses status codes 是否完整映射源码逻辑。
二、通过侧边栏问答交互提取API元数据
当代码缺乏类型提示或注释稀疏时，可借助CodeGeeX侧边栏的智能问答能力，以自然语言提问方式驱动结构化文档抽取。该方式绕过静态解析限制，适用于动态语言或遗留项目。
1、点击VS Code左侧活动栏中的 CodeGeeX图标，打开侧边栏面板。
2、输入问题，例如：“请根据以下Flask路由函数生成OpenAPI v3.0.3 YAML格式的API文档，包含请求体示例和200/400响应描述”。
3、选中目标函数代码，拖拽至聊天输入框，或点击“附加代码”按钮上传代码片段。
4、等待模型响应，复制返回的YAML内容至openapi.yaml文件中，并验证paths字段是否覆盖所有HTTP动词与路径变量。
三、配置本地LLM服务注入自定义文档模板
为统一团队文档风格，可通过本地部署兼容OpenAI API的模型服务，将预设的API文档模板注入system prompt，强制输出指定格式。此方法支持字段级控制，如是否包含curl示例、是否启用deprecated标记等。
1、启动本地大模型服务（如Ollama运行codegeex4-all-9b），确保其监听地址为http://localhost:11434/v1/chat/completions。
CodeGeeX 2.21.0是智谱AI推出的AI编程助手版本，对Inline Chat功能进行了重大优化，包括UI设计升级、支持流式输出以提升响应速度，并新增“查看思路”按钮以便理解代码原理。同时，该版本在编辑器中新增CodeLens控件，支持一键“解释”代码或“添加注释”。目前该工具对个人开发者免费开放。
2、在CodeGeeX插件设置中进入「本地模式」→「模型」页面，填写：
模型地址：http://localhost:11434/v1/chat/completions；
API KEY：ollama（若Ollama未设密钥则留空）；
模型名称：codegeex4-all-9b。
3、在「高级配置」→「聊天」中，将system prompt替换为：
“你是一个API文档工程师，严格按Swagger 2.0 JSON Schema输出，不得添加解释性文字。字段必须包含：swagger、info、host、basePath、paths、definitions。”
4、再次对函数调用文档生成指令，确认输出JSON结构中info.version与paths["/user/{id}"].get.parameters[0].name等路径参数命名与源码完全一致。
四、结合JSDoc/Pydoc注释规范触发精准解析
CodeGeeX对标准化注释语法具有高识别率，启用JSDoc（JavaScript/TypeScript）或Google Style Pydoc（Python）可显著提升参数类型、默认值、必填性等字段的提取准确率。该方法要求开发者前置编写轻量注释，但一次投入长期受益。
1、在函数上方添加JSDoc块，例如：
/**\n * @function createUser\n * @description 创建新用户并返回JWT令牌\n * @param {Object} userData - 用户基本信息\n * @param {string} userData.email - 邮箱地址，必填\n * @param {number} [userData.age=18] - 年龄，默认18\n * @returns {Promise<{token: string, userId: number}>}\n */
2、保存文件后，右键点击函数名，选择 “CodeGeeX: Generate API Doc”。
3、观察生成文档中requestBody.content.application/json.schema.properties是否包含email（required）、age（default: 18）等字段。
4、若缺失，检查注释中@param后是否遗漏花括号类型声明，或@returns是否使用了非标准语法。
五、使用CLI工具批量导出项目级API文档
针对含多个路由文件的中大型项目，可通过CodeGeeX提供的命令行工具扫描整个目录，聚合所有端点并生成完整OpenAPI文档。该方式避免逐个函数操作，适合CI/CD流程集成。
1、在项目根目录执行：
npx codegeex-cli docgen --src ./src/routes --output ./docs/openapi.json --lang ts
2、确认CLI输出日志中显示 “Found 12 endpoints across 5 files”，且无Parse error或Missing @description警告。
3、打开生成的openapi.json，验证paths对象下是否包含所有HTTP方法组合，例如GET /api/v1/users与POST /api/v1/users是否分属不同键名。
4、运行swagger-cli validate ./docs/openapi.json，确保返回API is valid而非schema validation failed。
