api-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Doc Generator

API 文档生成器

Generates markdown documentation from your OpenAPI Specification, creating multiple pages with curl command examples for each endpoint.

根据你的 OpenAPI Specification 生成 Markdown 文档，为每个 endpoint 创建独立页面，并附带 curl 命令示例。

When to Use This Skill

何时使用此 Skill

Use this skill when:

You need to create developer documentation from your API spec
You want to provide curl examples for each endpoint
You need human-readable documentation separate from the OAS file
You're building a documentation website or wiki

在以下情况下使用此 skill：

你需要根据 API spec 创建开发者文档
你希望为每个 endpoint 提供 curl 示例
你需要与 OAS 文件分离的人类可读文档
你正在构建文档网站或 wiki

Prerequisites

前置条件

bash

pip install pyyaml

bash

pip install pyyaml

Running Documentation Generator

运行文档生成器

bash

python3 skills/api-doc-generator/scripts/generate_docs.py path/to/spec.yaml [output-dir]

Default output directory is

./docs

if not specified.

bash

python3 skills/api-doc-generator/scripts/generate_docs.py path/to/spec.yaml [output-dir]

如果未指定，默认输出目录为

./docs

。

What Gets Generated

生成内容

The tool creates:

README.md (Overview page):
- API title, version, and description
- List of base URLs/servers
- Table of contents organized by tags
- Links to all endpoint pages
Individual endpoint pages (one per operation):
- HTTP method and path
- Description and summary
- Parameters table (path, query, header)
- Request body details
- Curl command examples with realistic values
- Response examples with status codes
- Response codes table

该工具会创建：

README.md（概览页）：
- API 标题、版本和描述
- 基础 URL/server 列表
- 按 tag 组织的目录
- 指向所有 endpoint 页面的链接
独立 endpoint 页面（每个 operation 一个）：
- HTTP method 和 path
- 描述和摘要
- 参数表（path、query、header）
- 请求体详情
- 使用真实示例值的 curl 命令示例
- 包含状态码的响应示例
- 响应码表

Example

示例

bash

undefined

bash

undefined

Generate docs to default ./docs directory

python3 skills/api-doc-generator/scripts/generate_docs.py api-spec.yaml

Generate docs to custom directory

python3 skills/api-doc-generator/scripts/generate_docs.py api-spec.yaml ./documentation


**Output:**

Generating API documentation from api-spec.yaml...

Generating overview page: README.md Generating endpoint page: createUser.md Generating endpoint page: getUserById.md Generating endpoint page: listOrders.md

✓ Generated documentation for 3 endpoints ✓ Output directory: ./docs

View the documentation:

Overview: ./docs/README.md

undefined

python3 skills/api-doc-generator/scripts/generate_docs.py api-spec.yaml ./documentation


**输出：**

Generating API documentation from api-spec.yaml...

Generating overview page: README.md Generating endpoint page: createUser.md Generating endpoint page: getUserById.md Generating endpoint page: listOrders.md

✓ Generated documentation for 3 endpoints ✓ Output directory: ./docs

View the documentation:

Overview: ./docs/README.md

undefined

Curl Examples

curl 示例

The tool automatically generates curl commands with:

Correct HTTP method
Base URL from servers configuration
Path parameters replaced with example values
Query parameters included
Headers included
Request body with proper JSON formatting
Multiple examples if the spec provides them

Example generated curl command:

bash

curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "age": 28,
  "role": "developer"
}'

该工具会自动生成包含以下内容的 curl 命令：

正确的 HTTP method
来自 servers 配置的基础 URL
使用示例值替换的 path 参数
包含的 query 参数
包含的 headers
使用正确 JSON 格式的请求体
如果 spec 提供了多个示例，则生成多个示例

生成的 curl 命令示例：

bash

curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "age": 28,
  "role": "developer"
}'

Organizing Documentation

组织文档

The generated documentation can be:

Committed to your repository in a
```
docs/
```
folder
Published to GitHub Pages or similar
Imported into a wiki or documentation platform
Shared with API consumers as standalone files

Each endpoint gets its own file, making it easy to:

Link directly to specific endpoints
Update individual endpoints without touching others
Organize in folders by tag/category if needed

生成的文档可以：

提交到 repository 中的
```
docs/
```
文件夹
发布到 GitHub Pages 或类似平台
导入 wiki 或文档平台
作为独立文件共享给 API 使用者

每个 endpoint 都有独立文件，便于：

直接链接到特定 endpoint
更新单个 endpoint，而不影响其他页面
根据需要按 tag/category 组织文件夹

Using with Claude

与 Claude 配合使用

Ask Claude to generate documentation:

"Generate markdown documentation from my API spec at path/to/spec.yaml"
"Create API docs with curl examples from specs/my-api.yaml"
"Generate developer documentation for my OpenAPI spec"

让 Claude 生成文档：

"Generate markdown documentation from my API spec at path/to/spec.yaml"
"Create API docs with curl examples from specs/my-api.yaml"
"Generate developer documentation for my OpenAPI spec"

api-doc-generator

Original

Translation

API Doc Generator

API 文档生成器

When to Use This Skill

何时使用此 Skill

Prerequisites

前置条件

Running Documentation Generator

运行文档生成器

What Gets Generated

生成内容

Example

示例

Generate docs to default ./docs directory

Generate docs to default ./docs directory

Generate docs to custom directory

Generate docs to custom directory

Curl Examples

curl 示例

Organizing Documentation

组织文档

Using with Claude

与 Claude 配合使用

Related Skills

相关 Skills