生成API文档的五种方法：一、基于代码注释用pydoc-markdown自动生成Markdown；二、从YAML配置提取元数据生成OpenAPI规范及Redoc HTML；三、集成Flask-RESTX实现实时Swagger UI；四、聚合技能目录中SKILL.md的Frontmatter生成技能API索引；五、抽取测试用例生成可运行的curl示例。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在为Hermes Agent构建API接口，但尚未生成配套文档，则可能是由于缺乏自动化文档生成机制。以下是生成API文档的多种可行方法：
一、基于代码注释的自动提取
该方法利用函数与类中已有的结构化注释（如Google或NumPy风格），直接解析参数、返回值、异常及功能描述，实现“代码即文档”。它无需额外编写文档源文件，确保文档与实现零延迟同步。
1、定位核心工具模块，例如tools/file_tools.py或tools/terminal_tool.py，确认其函数包含完整docstring。
2、安装并运行pydoc-markdown工具，配置pydoc-markdown.yml指定输入路径与输出格式为Markdown。
3、执行命令pydoc-markdown -I . -o docs/api-reference.md，生成可读性强的参考文档。
二、YAML配置驱动的元数据生成
项目中的环境配置文件（如environments/hermes_swe_env/default.yaml）已声明API端点、认证方式、超时等元数据。通过轻量脚本提取这些字段，可批量生成标准化接口清单，避免人工遗漏关键配置项。
1、编写Python脚本，使用PyYAML加载default.yaml，提取base_url、api_key_env、endpoints等键值。
2、将提取结果映射为OpenAPI 3.0规范中的servers与paths结构，保存为openapi.yaml。
3、使用redoc-cli生成静态HTML文档：npx redoc-cli bundle openapi.yaml -o docs/redoc.html。
三、集成Flask-RESTX自动生成Swagger UI
若Hermes Agent后端采用Flask框架暴露HTTP API，可通过Flask-RESTX在定义接口的同时内嵌Swagger支持，实现实时交互式文档页面，开发者可直接试用端点。
1、在requirements.txt中添加flask-restx==1.1.0与swagger-ui-bundle==0.0.9。
2、修改tools/web_tools.py，导入Api与Resource，用@api.doc装饰器标注参数与响应模型。
3、启动服务后访问/swagger路径，即可查看带UI的实时API文档页面。
四、技能文档标准化聚合
针对skills/目录下的每个技能（如skills/github/github-issues/SKILL.md），其Frontmatter中已定义name、triggers、tools_required等字段。聚合这些结构化元数据，可生成统一的技能API目录，作为面向用户的轻量级接口说明。
1、遍历skills/**/SKILL.md，用正则或frontmatter库提取YAML头信息。
2、按triggers字段归类，生成表格形式的触发词-功能映射表。
3、将结果写入docs/skills-api-index.md，并嵌入至主文档导航中。
五、测试用例驱动的示例同步
测试文件中已存在的合法调用与断言，天然具备准确性与可运行性。将其抽取为文档示例，可确保用户所见即所得，杜绝“文档能看、代码不能跑”的问题。
1、扫描tests/tools/目录下所有test_*.py文件，识别含requests.post或hermes_client.call的测试函数。
2、提取请求URL、headers、JSON payload及预期响应断言，转为curl与JSON代码块。
3、将生成的示例插入对应API文档的## 示例章节，每例标注测试文件来源路径。
