api-reference-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Reference Documentation

API参考文档

Overview

概述

Generate professional API documentation that developers can use to integrate with your API, including endpoint specifications, authentication, request/response examples, and interactive documentation.

生成可供开发者集成使用的专业API文档，包括端点规范、认证机制、请求/响应示例以及交互式文档。

When to Use

适用场景

Documenting REST APIs
Creating OpenAPI/Swagger specifications
GraphQL API documentation
SDK and client library docs
API authentication guides
Rate limiting documentation
Webhook documentation
API versioning guides

编写REST API文档
创建OpenAPI/Swagger规范
GraphQL API文档编写
SDK及客户端库文档编写
API认证指南编写
速率限制文档编写
Webhook文档编写
API版本控制指南编写

OpenAPI Specification Example

OpenAPI规范示例

yaml

openapi: 3.0.3
info:
  title: E-Commerce API
  description: |
    Complete API for managing e-commerce operations including products,
    orders, customers, and payments.

    ## Authentication
    All endpoints require Bearer token authentication. Include your API key
    in the Authorization header: `Authorization: Bearer YOUR_API_KEY`

    ## Rate Limiting
    - 1000 requests per hour for authenticated users
    - 100 requests per hour for unauthenticated requests

    ## Pagination
    List endpoints return paginated results with `page` and `limit` parameters.
  version: 2.0.0
  contact:
    name: API Support
    email: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: Production server
  - url: https://staging-api.example.com/v2
    description: Staging server
  - url: http://localhost:3000/v2
    description: Local development

tags:
  - name: Products
    description: Product management operations
  - name: Orders
    description: Order processing and tracking
  - name: Customers
    description: Customer management
  - name: Authentication
    description: Authentication endpoints

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login endpoint

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for server-to-server authentication

  schemas:
    Product:
      type: object
      required:
        - name
        - price
        - sku
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          minLength: 1
          maxLength: 200
          example: "Wireless Headphones"
        description:
          type: string
          maxLength: 2000
          example: "Premium noise-cancelling wireless headphones"
        price:
          type: number
          format: float
          minimum: 0
          example: 299.99
        sku:
          type: string
          pattern: '^[A-Z0-9-]+$'
          example: "WH-1000XM5"
        category:
          type: string
          enum: [electronics, clothing, books, home, sports]
          example: "electronics"
        stock:
          type: integer
          minimum: 0
          example: 150
        images:
          type: array
          items:
            type: string
            format: uri
          example:
            - "https://cdn.example.com/products/wh-1000xm5-1.jpg"
            - "https://cdn.example.com/products/wh-1000xm5-2.jpg"
        tags:
          type: array
          items:
            type: string
          example: ["wireless", "bluetooth", "noise-cancelling"]
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    Order:
      type: object
      required:
        - customerId
        - items
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        customerId:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          default: pending
        totalAmount:
          type: number
          format: float
          readOnly: true
        shippingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time
          readOnly: true

    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
        price:
          type: number
          format: float
          readOnly: true

    Address:
      type: object
      required:
        - street
        - city
        - country
        - postalCode
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

    PaginatedProducts:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "UNAUTHORIZED"
            message: "Authentication token is missing or invalid"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "NOT_FOUND"
            message: "The requested resource was not found"

paths:
  /products:
    get:
      summary: List products
      description: Retrieve a paginated list of products with optional filtering
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
        - name: maxPrice
          in: query
          schema:
            type: number
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProducts'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create product
      description: Create a new product
      tags:
        - Products
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              headphones:
                summary: Wireless headphones
                value:
                  name: "Wireless Headphones"
                  description: "Premium noise-cancelling"
                  price: 299.99
                  sku: "WH-1000XM5"
                  category: "electronics"
                  stock: 150
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /products/{productId}:
    get:
      summary: Get product
      description: Retrieve a specific product by ID
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          $ref: '#/components/responses/NotFound'

yaml

openapi: 3.0.3
info:
  title: E-Commerce API
  description: |
    Complete API for managing e-commerce operations including products,
    orders, customers, and payments.

    ## Authentication
    All endpoints require Bearer token authentication. Include your API key
    in the Authorization header: `Authorization: Bearer YOUR_API_KEY`

    ## Rate Limiting
    - 1000 requests per hour for authenticated users
    - 100 requests per hour for unauthenticated requests

    ## Pagination
    List endpoints return paginated results with `page` and `limit` parameters.
  version: 2.0.0
  contact:
    name: API Support
    email: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: Production server
  - url: https://staging-api.example.com/v2
    description: Staging server
  - url: http://localhost:3000/v2
    description: Local development

tags:
  - name: Products
    description: Product management operations
  - name: Orders
    description: Order processing and tracking
  - name: Customers
    description: Customer management
  - name: Authentication
    description: Authentication endpoints

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login endpoint

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for server-to-server authentication

  schemas:
    Product:
      type: object
      required:
        - name
        - price
        - sku
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          minLength: 1
          maxLength: 200
          example: "Wireless Headphones"
        description:
          type: string
          maxLength: 2000
          example: "Premium noise-cancelling wireless headphones"
        price:
          type: number
          format: float
          minimum: 0
          example: 299.99
        sku:
          type: string
          pattern: '^[A-Z0-9-]+$'
          example: "WH-1000XM5"
        category:
          type: string
          enum: [electronics, clothing, books, home, sports]
          example: "electronics"
        stock:
          type: integer
          minimum: 0
          example: 150
        images:
          type: array
          items:
            type: string
            format: uri
          example:
            - "https://cdn.example.com/products/wh-1000xm5-1.jpg"
            - "https://cdn.example.com/products/wh-1000xm5-2.jpg"
        tags:
          type: array
          items:
            type: string
          example: ["wireless", "bluetooth", "noise-cancelling"]
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    Order:
      type: object
      required:
        - customerId
        - items
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        customerId:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          default: pending
        totalAmount:
          type: number
          format: float
          readOnly: true
        shippingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time
          readOnly: true

    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
        price:
          type: number
          format: float
          readOnly: true

    Address:
      type: object
      required:
        - street
        - city
        - country
        - postalCode
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

    PaginatedProducts:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "UNAUTHORIZED"
            message: "Authentication token is missing or invalid"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "NOT_FOUND"
            message: "The requested resource was not found"

paths:
  /products:
    get:
      summary: List products
      description: Retrieve a paginated list of products with optional filtering
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
        - name: maxPrice
          in: query
          schema:
            type: number
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProducts'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create product
      description: Create a new product
      tags:
        - Products
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              headphones:
                summary: Wireless headphones
                value:
                  name: "Wireless Headphones"
                  description: "Premium noise-cancelling"
                  price: 299.99
                  sku: "WH-1000XM5"
                  category: "electronics"
                  stock: 150
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /products/{productId}:
    get:
      summary: Get product
      description: Retrieve a specific product by ID
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          $ref: '#/components/responses/NotFound'

Markdown Documentation Template

Markdown文档模板

markdown

undefined

markdown

undefined

Products API

产品API

Overview

概述

The Products API allows you to manage your product catalog, including creating, updating, retrieving, and deleting products.

产品API用于管理商品目录，包括商品的创建、更新、查询和删除操作。

Base URL

基础URL

https://api.example.com/v2

https://api.example.com/v2

Authentication

认证机制

All API requests require authentication using a Bearer token:

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v2/products

所有API请求都需要使用Bearer令牌进行认证：

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v2/products

Endpoints

端点

List Products

查询商品列表

Retrieve a paginated list of products.

Endpoint:

GET /products

Query Parameters:

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20)
category	string	No	Filter by category
search	string	No	Search in name/description

Example Request:

bash

curl -X GET "https://api.example.com/v2/products?page=1&limit=20&category=electronics" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Wireless Headphones",
      "description": "Premium noise-cancelling wireless headphones",
      "price": 299.99,
      "sku": "WH-1000XM5",
      "category": "electronics",
      "stock": 150,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Responses:

Status Code	Description
400	Invalid parameters
401	Unauthorized
500	Internal server error

undefined

获取分页的商品列表。

端点：

GET /products

查询参数：

参数名	类型	是否必填	描述
page	数字	否	页码（默认值：1）
limit	数字	否	每页数量（默认值：20）
category	字符串	否	按分类筛选
search	字符串	否	按名称/描述搜索

请求示例：

bash

curl -X GET "https://api.example.com/v2/products?page=1&limit=20&category=electronics" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例：

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Wireless Headphones",
      "description": "Premium noise-cancelling wireless headphones",
      "price": 299.99,
      "sku": "WH-1000XM5",
      "category": "electronics",
      "stock": 150,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

错误响应：

状态码	描述
400	参数无效
401	未授权
500	服务器内部错误

undefined

Best Practices

最佳实践

✅ DO

✅ 建议做法

Use OpenAPI 3.0+ specification
Include request/response examples for every endpoint
Document all query parameters and headers
Provide authentication examples
Include error response formats
Document rate limits and pagination
Use consistent naming conventions
Include SDK examples in multiple languages
Document webhook payloads
Provide interactive API explorer (Swagger UI)
Version your API documentation
Include migration guides for breaking changes

使用OpenAPI 3.0+规范
为每个端点提供请求/响应示例
记录所有查询参数和请求头
提供认证示例
包含错误响应格式
记录速率限制和分页机制
使用一致的命名约定
提供多语言SDK示例
记录Webhook负载
提供交互式API探索工具（Swagger UI）
为API文档添加版本标识
包含破坏性变更的迁移指南

❌ DON'T

❌ 避免做法

Skip error response documentation
Forget to document authentication
Use inconsistent terminology
Leave endpoints undocumented
Ignore deprecation notices
Skip versioning information

遗漏错误响应文档
忘记记录认证机制
使用不一致的术语
留下未记录的端点
忽略弃用通知
遗漏版本信息

api-reference-documentation

Original

Translation

API Reference Documentation

API参考文档

Overview

概述

When to Use

适用场景

OpenAPI Specification Example

OpenAPI规范示例

Markdown Documentation Template

Markdown文档模板

Products API

产品API

Overview

概述

Base URL

基础URL

Authentication

认证机制

Endpoints

端点

List Products

查询商品列表

Best Practices

最佳实践

✅ DO

✅ 建议做法

❌ DON'T

❌ 避免做法

Resources

相关资源