步骤 2：从代码生成文档 (JSDoc/装饰器)

Express + TypeScript :

/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               password:
 *                 type: string
 *                 minLength: 8
 *     responses:
 *       201:
 *         description: User created successfully
 *       400:
 *         description: Invalid input
 */
router.post('/users', async (req, res) => {
  const { email, name, password } = req.body;
  const user = await userService.createUser({ email, name, password });
  res.status(201).json(user);
});

步骤 3：交互式文档

Swagger UI 设置 :

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: "My API Documentation"
}));

步骤 4：示例与指南

## API 文档

### 身份验证

所有 API 请求都需要使用 JWT 令牌进行身份验证。

#### 获取令牌
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`

响应：
\`\`\`json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}
\`\`\`

#### 使用令牌
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`

### 创建用户

**端点**：`POST /v1/users`

**请求体**：
\`\`\`json
{
  "email": "john@example.com",
  "name": "John Doe",
  "password": "SecurePass123!"
}
\`\`\`

**成功响应** (201)：
\`\`\`json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`

**错误响应** (400)：
\`\`\`json
{
  "error": "Email already exists"
}
\`\`\`

### 速率限制
- 每个 IP 每 15 分钟 100 个请求
- 响应头：`X-RateLimit-Remaining`

### 分页
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`

响应包含分页信息：
\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 157,
    "pages": 8
  }
}
\`\`\`

### 错误码
- `400` - 错误请求（验证错误）
- `401` - 未授权（缺少/无效令牌）
- `403` - 禁止访问（权限不足）
- `404` - 未找到
- `409` - 冲突（重复资源）
- `429` - 请求过多（速率限制）
- `500` - 内部服务器错误

输出格式

API 文档结构

docs/
├── README.md                    # 概述
├── getting-started.md           # 快速入门指南
├── authentication.md            # 身份验证指南
├── api-reference/
│   ├── users.md                 # 用户相关端点
│   ├── auth.md                  # 身份验证端点
│   └── products.md              # 产品相关端点
├── guides/
│   ├── pagination.md
│   ├── error-handling.md
│   └── rate-limiting.md
├── examples/
│   ├── curl.md
│   ├── javascript.md
│   └── python.md
└── openapi.yaml                 # OpenAPI 规范

约束条件

必需规则 (MUST)

1. 真实示例 : 提供可运行的代码示例
2. 错误情况 : 不仅记录成功情况，也要记录失败情况
3. 保持更新 : API 变更时更新文档

禁止事项 (MUST NOT)

1. 示例中使用真实密钥 : 不要在示例中使用真实的 API 密钥/密码
2. 模糊描述 : 避免使用如"返回数据"等不清晰的描述

最佳实践

1. 提供试用功能 : 提供交互式文档 (Swagger UI)
2. 提供 SDK : 为主要编程语言提供 SDK 和示例
3. 更新日志 : 记录 API 变更

参考资源

• OpenAPI 规范
• Swagger UI
• Redoc

元数据

版本信息

• 当前版本 : 1.0.0
• 最后更新 : 2025-01-01
• 兼容平台 : Claude, ChatGPT, Gemini

标签

#API-documentation #OpenAPI #Swagger #REST #developer-docs #documentation

示例

示例 1：基本用法

示例 2：高级用法

每周安装数

1

代码仓库

akillness/oh-my-gods

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1

Step 2: Generate Documentation from Code (JSDoc/Decorators)

Express + TypeScript :

/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               password:
 *                 type: string
 *                 minLength: 8
 *     responses:
 *       201:
 *         description: User created successfully
 *       400:
 *         description: Invalid input
 */
router.post('/users', async (req, res) => {
  const { email, name, password } = req.body;
  const user = await userService.createUser({ email, name, password });
  res.status(201).json(user);
});

Step 3: Interactive Documentation

Swagger UI Setup :

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: "My API Documentation"
}));

Step 4: Examples & Guides

## API Documentation

### Authentication

All API requests require authentication using JWT tokens.

#### Getting a Token
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`

Response:
\`\`\`json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}
\`\`\`

#### Using the Token
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`

### Creating a User

**Endpoint**: `POST /v1/users`

**Request Body**:
\`\`\`json
{
  "email": "john@example.com",
  "name": "John Doe",
  "password": "SecurePass123!"
}
\`\`\`

**Success Response** (201):
\`\`\`json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`

**Error Response** (400):
\`\`\`json
{
  "error": "Email already exists"
}
\`\`\`

### Rate Limiting
- 100 requests per 15 minutes per IP
- Header: `X-RateLimit-Remaining`

### Pagination
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`

Response includes pagination info:
\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 157,
    "pages": 8
  }
}
\`\`\`

### Error Codes
- `400` - Bad Request (validation error)
- `401` - Unauthorized (missing/invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `429` - Too Many Requests (rate limit)
- `500` - Internal Server Error

Output format

API Documentation Structure

docs/
├── README.md                    # Overview
├── getting-started.md           # Quick start guide
├── authentication.md            # Auth guide
├── api-reference/
│   ├── users.md                 # Users endpoints
│   ├── auth.md                  # Auth endpoints
│   └── products.md              # Products endpoints
├── guides/
│   ├── pagination.md
│   ├── error-handling.md
│   └── rate-limiting.md
├── examples/
│   ├── curl.md
│   ├── javascript.md
│   └── python.md
└── openapi.yaml                 # OpenAPI spec

Constraints

Required Rules (MUST)

1. Real Examples : Provide working code examples
2. Error Cases : Document not only success but also failure cases
3. Keep Updated : Update documentation when API changes

Prohibited (MUST NOT)

1. Real Keys in Examples : Do not use real API keys/passwords in examples
2. Vague Descriptions : Unclear descriptions like "returns data"

Best practices

1. Try It Out : Provide interactive documentation (Swagger UI)
2. Provide SDK : SDK and examples for major languages
3. Changelog : Document API changes

References

• OpenAPI Specification
• Swagger UI
• Redoc

Metadata

Version

• Current Version : 1.0.0
• Last Updated : 2025-01-01
• Compatible Platforms : Claude, ChatGPT, Gemini

Tags

#API-documentation #OpenAPI #Swagger #REST #developer-docs #documentation

Examples

Example 1: Basic usage

Example 2: Advanced usage

Weekly Installs

1

Repository

akillness/oh-my-gods

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1