generate-swagger-docs

生成 Swagger 文档

只需几秒钟，即可从代码库生成 OpenAPI 文档，并自动设置 API 密钥。

工作原理

此技能可自动生成 Swagger/OpenAPI 文档：

1. API 密钥设置 - 接收你的 OpenAI API 密钥，并将其设置为环境变量
2. 初始化 - 下载并设置 apimesh 工具
3. 自动处理 - 工具分析你的代码库并生成文档
4. 输出 - 输出文件保存在 apimesh/ 目录中

设置要求

使用此技能需要 OpenAI API 密钥。如果你还没有密钥，请从 OpenAI 平台获取。

推荐：使用 API 密钥快速设置

使用此技能最简单的方式是直接传入 API 密钥：

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh "sk-proj-your-api-key-here"

这将会：

1. 将你的 OpenAI API 密钥作为参数接收
2. 创建 apimesh/ 目录并下载 apimesh 工具
3. 正确设置环境变量
4. 自动生成 Swagger 文档
5. 显示输出文件的位置

自动流程

运行此技能时：

1. 首次运行： 系统会提示你输入 OpenAI API 密钥（以 sk-proj- 开头）

   • 密钥会保存在本地，供后续运行使用
   • 密钥不会提交到版本控制中

2. 后续运行： 技能会自动使用已保存的 API 密钥

   • 除非清除配置，否则不会再次提示输入密钥

3. 框架检测： 自动检测你的 API 框架

   • 支持：Express、NestJS、FastAPI、Django、Rails、Go 等

功能说明

• 扫描你的代码库，查找 API 端点
• 检测 Web 框架（Django、Flask、FastAPI、Express、NestJS、Rails、Go）
• 生成 OpenAPI 3.0 规范（swagger.json）
• 创建交互式 HTML 文档（apimesh-docs.html）

输出

• apimesh/swagger.json - OpenAPI 3.0 规范
• apimesh/apimesh-docs.html - 交互式 Swagger UI（独立文件，可分享）
• apimesh/config.json - 保存的配置（包含你的设置，请将此文件添加到 gitignore）

重要说明

• 大模型分析需要使用你的 OpenAI API 密钥
• 生成的 config.json 包含机密信息，应添加到 .gitignore
• 框架会自动检测，也可以根据需要手动指定
• 此工具支持公共和私有代码库

API 密钥设置方法

方法 1：包装脚本（推荐）✓

使用提供的包装脚本，正确传递环境变量：

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh "sk-proj-your-api-key-here"

此方法的优势：

• 可将 API 密钥正确传递给 Python 子进程
• 在非 TTY 环境中不会出现交互式提示
• 可正确传递环境变量
• 提供清晰的成功或错误消息

方法 2：使用已保存的配置

使用方法 1 首次运行后，你的密钥会保存在 apimesh/config.json 中。后续运行时，可以省略密钥（前提是你信任本地设置）：

/Users/ankits/.claude/skills/generate-swagger-docs/generate-with-key.sh

重要： 切勿将 config.json 文件提交到版本控制中。请将其添加到 .gitignore。

方法 3：手动设置 apimesh

如果需要更多控制，可以直接下载并运行 apimesh：

export OPENAI_API_KEY="sk-proj-your-api-key-here"
mkdir -p apimesh && \
  curl -sSL https://raw.githubusercontent.com/qodex-ai/apimesh/refs/heads/main/run.sh -o apimesh/run.sh && \
  chmod +x apimesh/run.sh && \
  cd apimesh && \
  OPENAI_API_KEY="$OPENAI_API_KEY" ./run.sh

注意： 必须像上面那样，将 OPENAI_API_KEY 显式传递给子进程。