generate-swagger-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Swagger Documentation

生成Swagger文档

Generate OpenAPI docs from your codebase in seconds with automatic API key setup.

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

How It Works

工作原理

This skill automates the Swagger/OpenAPI documentation generation:

API Key Setup - Accepts your OpenAI API key and sets it as an environment variable
Initialization - Downloads and sets up the apimesh tool
Automatic Processing - The tool analyzes your codebase and generates documentation
Output - Outputs are saved to the apimesh/ directory

本Skill可自动完成Swagger/OpenAPI文档生成：

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

Setup Requirements

配置要求

You need an OpenAI API key to use this skill. Get one from OpenAI's platform if you don't have one already.

使用本Skill需要OpenAI API密钥。如果还没有，可以从OpenAI平台获取。

Recommended: Quick Setup with API Key

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

The easiest way to use this skill is to pass your API key directly:

bash

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

This will:

Accept your OpenAI API key as an argument
Create the
```
apimesh/
```
directory and download the apimesh tool
Set up the environment variables correctly
Generate your Swagger documentation automatically
Display the output file locations

使用本Skill最简单的方式是直接传入你的API密钥：

bash

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

该命令将：

接收你的API密钥作为参数
创建
```
apimesh/
```
目录并下载apimesh工具
正确配置环境变量
自动生成Swagger文档
显示输出文件的位置

Automatic Flow

自动流程

When you run this skill:

First Time: You'll be prompted for your OpenAI API key (starts with
```
sk-proj-
```
)
- The key is saved locally and used for subsequent runs
- The key is NOT committed to version control
Subsequent Runs: The skill uses the saved API key automatically
- No additional prompts for the key unless you clear the config
Framework Detection: Automatically detects your API framework
- Supports: Express, NestJS, FastAPI, Django, Rails, Go, and more

运行本Skill时：

首次运行：系统会提示你输入OpenAI API密钥（以
```
sk-proj-
```
开头）
- 密钥将保存在本地，供后续运行使用
- 密钥不会提交至版本控制系统
后续运行：Skill将自动使用已保存的API密钥
- 除非你清除配置，否则不会再提示输入密钥
框架检测：自动检测你的API框架
- 支持：Express、NestJS、FastAPI、Django、Rails、Go等

What It Does

功能说明

Scans your repository for API endpoints
Detects the web framework (Django, Flask, FastAPI, Express, NestJS, Rails, Go)
Generates OpenAPI 3.0 specification (
```
swagger.json
```
)
Creates interactive HTML documentation (
```
apimesh-docs.html
```
)

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

Output

输出文件

```
apimesh/swagger.json
```
- OpenAPI 3.0 spec
```
apimesh/apimesh-docs.html
```
- Interactive Swagger UI (self-contained, shareable)
```
apimesh/config.json
```
- Saved configuration (includes your settings, gitignore this file)

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

Important Notes

重要说明

Your OpenAI API key is needed for the LLM analysis
The generated
```
config.json
```
should be added to
```
.gitignore
```
as it contains secrets
Framework detection is automatic but can be manually specified if needed
The tool supports both public and private repositories

进行LLM分析需要你的OpenAI API密钥
生成的
```
config.json
```
文件包含敏感信息，需添加到
```
.gitignore
```
中
框架检测为自动完成，如有需要也可手动指定
工具支持公开和私有代码仓库

API Key Setup Methods

API密钥配置方法

Method 1: Wrapper Script (Recommended) ✓

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

Use the provided wrapper script that properly handles environment variable propagation:

bash

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

Why this works best:

Properly passes the API key to the Python subprocess
No interactive prompts in non-TTY environments
Handles environment variable propagation correctly
Provides clear success/error messages

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

bash

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

推荐原因：

正确将API密钥传递给Python子进程
在非TTY环境中无需交互式提示
正确处理环境变量传递
提供清晰的成功/错误提示

Method 2: Using Saved Configuration

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

After the first run with Method 1, your key is saved in

apimesh/config.json

. On subsequent runs, you can omit the key (if you trust your local setup):

bash

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

Important: Never commit the

config.json

file to version control. Add it to

.gitignore

首次使用方法1运行后，你的密钥将保存在

apimesh/config.json

中。后续运行时，若信任本地环境，可省略密钥参数：

bash

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

重要提示： 切勿将

config.json

文件提交至版本控制系统，需将其加入

.gitignore

。

Method 3: Manual apimesh Setup

方法3：手动配置apimesh

If you need more control, download and run apimesh directly:

bash

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

Note: The

OPENAI_API_KEY

must be explicitly passed to the subprocess as shown above.

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

bash

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

传递给子进程。