api-docs-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Documentation Generator

API文档生成指南

Quick Start

快速开始

Generate API docs based on code type:

bash

undefined

根据代码类型生成API文档：

bash

undefined

OpenAPI from Express routes

从Express路由生成OpenAPI文档

npx swagger-jsdoc -d swaggerDef.js routes/*.js

JSDoc for JavaScript

为JavaScript生成JSDoc文档

npx jsdoc src/ -d docs/

Python docstrings

处理Python文档字符串

pdoc --html --output-dir docs/ mypackage/

undefined

pdoc --html --output-dir docs/ mypackage/

undefined

Instructions

操作步骤

Step 1: Identify API Type

步骤1：确定API类型

Determine documentation approach:

API Type	Tool	Output
REST API	OpenAPI/Swagger	Interactive API docs
GraphQL	GraphQL Schema	Schema documentation
JavaScript Library	JSDoc	HTML reference
Python Library	Sphinx/pdoc	HTML reference

选择对应的文档生成方式：

API类型	工具	输出结果
REST API	OpenAPI/Swagger	交互式API文档
GraphQL	GraphQL Schema	架构文档
JavaScript库	JSDoc	HTML参考文档
Python库	Sphinx/pdoc	HTML参考文档

Step 2: Extract Documentation

步骤2：提取文档信息

REST API (OpenAPI):

Scan route files for JSDoc comments:

javascript

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */
router.get('/users', getUsers);

Generate spec:

bash

npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

JavaScript Library (JSDoc):

javascript

/**
 * Adds two numbers together.
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * add(2, 3); // returns 5
 */
function add(a, b) {
  return a + b;
}

Python (Docstrings):

python

def add(a: int, b: int) -> int:
    """Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Sum of a and b
        
    Example:
        >>> add(2, 3)
        5
    """
    return a + b

REST API（OpenAPI）：

扫描路由文件中的JSDoc注释：

javascript

/**
 * @swagger
 * /users:
 *   get:
 *     summary: 获取所有用户
 *     responses:
 *       200:
 *         description: 用户列表
 */
router.get('/users', getUsers);

生成规范文件：

bash

npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

JavaScript库（JSDoc）：

javascript

/**
 * 将两个数字相加。
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} a和b的和
 * @example
 * add(2, 3); // 返回5
 */
function add(a, b) {
  return a + b;
}

Python（文档字符串）：

python

def add(a: int, b: int) -> int:
    """将两个数字相加。
    
    参数:
        a: 第一个数字
        b: 第二个数字
        
    返回:
        a和b的和
        
    示例:
        >>> add(2, 3)
        5
    """
    return a + b

Step 3: Generate Documentation

步骤3：生成文档

OpenAPI/Swagger:

bash

undefined

OpenAPI/Swagger：

bash

undefined

Generate OpenAPI spec

生成OpenAPI规范文件

npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

Serve interactive docs

启动交互式文档服务

npx swagger-ui-express openapi.json


**JSDoc:**
```bash
npx jsdoc src/ -d docs/ -r

Python Sphinx:

bash

sphinx-apidoc -o docs/source mypackage/
cd docs && make html

Python pdoc:

bash

pdoc --html --output-dir docs/ mypackage/

npx swagger-ui-express openapi.json


**JSDoc：**
```bash
npx jsdoc src/ -d docs/ -r

Python Sphinx：

bash

sphinx-apidoc -o docs/source mypackage/
cd docs && make html

Python pdoc：

bash

pdoc --html --output-dir docs/ mypackage/

Step 4: Organize Output

步骤4：整理输出结构

Structure documentation:

docs/
├── api/
│   ├── openapi.json       # OpenAPI specification
│   ├── index.html         # Interactive API docs
│   └── endpoints/         # Endpoint details
├── reference/
│   ├── classes/           # Class documentation
│   ├── functions/         # Function documentation
│   └── types/             # Type definitions
└── guides/
    ├── authentication.md  # Auth guide
    └── examples.md        # Usage examples

规划文档目录结构：

docs/
├── api/
│   ├── openapi.json       # OpenAPI规范文件
│   ├── index.html         # 交互式API文档
│   └── endpoints/         # 端点详情
├── reference/
│   ├── classes/           # 类文档
│   ├── functions/         # 函数文档
│   └── types/             # 类型定义
└── guides/
    ├── authentication.md  # 认证指南
    └── examples.md        # 使用示例

Step 5: Add Examples

步骤5：添加示例

Include practical examples:

markdown

undefined

包含实用的代码示例：

markdown

undefined

Authentication

认证说明

All API requests require authentication:

```bash curl -H "Authorization: Bearer TOKEN" \ https://api.example.com/v1/users ```

```javascript const response = await fetch('https://api.example.com/v1/users', { headers: { 'Authorization': 'Bearer TOKEN' } }); ```

```python import requests

response = requests.get( 'https://api.example.com/v1/users', headers={'Authorization': 'Bearer TOKEN'} ) ```

undefined

所有API请求都需要认证：

bash

curl -H "Authorization: Bearer TOKEN" \\
  https://api.example.com/v1/users

javascript

const response = await fetch('https://api.example.com/v1/users', {
  headers: { 'Authorization': 'Bearer TOKEN' }
});

python

import requests

response = requests.get(
    'https://api.example.com/v1/users',
    headers={'Authorization': 'Bearer TOKEN'}
)

undefined

OpenAPI Specification

OpenAPI规范

Basic Structure

基础结构

yaml

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

yaml

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API描述

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

api-docs-generator

Original

Translation

API Documentation Generator

API文档生成指南

Quick Start

快速开始

OpenAPI from Express routes

从Express路由生成OpenAPI文档

JSDoc for JavaScript

为JavaScript生成JSDoc文档

Python docstrings

处理Python文档字符串

Instructions

操作步骤

Step 1: Identify API Type

步骤1：确定API类型

Step 2: Extract Documentation

步骤2：提取文档信息

Step 3: Generate Documentation

步骤3：生成文档

Generate OpenAPI spec

生成OpenAPI规范文件

Serve interactive docs

启动交互式文档服务

Step 4: Organize Output

步骤4：整理输出结构

Step 5: Add Examples

步骤5：添加示例

Authentication

认证说明

OpenAPI Specification

OpenAPI规范

Basic Structure

基础结构

Documentation Checklist

文档检查清单