Back to Details

api-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Documentation

API文档

OpenAPI/Swagger Specification Standards

OpenAPI/Swagger规范标准

OpenAPI 3.0 Specification

OpenAPI 3.0规范

  • OpenAPI Object: Root object containing API metadata and paths
  • Info Object: API title, version, description, and contact information
  • Paths Object: Available endpoints and operations
  • Components Object: Reusable schemas, parameters, responses, and examples
  • Security Object: Authentication and authorization schemes
  • Servers Object: API server URLs and configurations
  • OpenAPI对象：包含API元数据和路径的根对象
  • 信息对象：API标题、版本、描述和联系信息
  • 路径对象：可用的端点和操作
  • 组件对象：可复用的模式、参数、响应和示例
  • 安全对象：认证与授权方案
  • 服务器对象：API服务器URL和配置

Key Elements

核心元素

  • Paths: Define endpoints with HTTP methods (GET, POST, PUT, DELETE, etc.)
  • Parameters: Query, path, header, and cookie parameters with types and constraints
  • Request Body: Payload schemas with content types (application/json, etc.)
  • Responses: Status codes, descriptions, and response schemas
  • Examples: Request and response examples for each operation
  • Tags: Group operations for organization and navigation
  • 路径：使用HTTP方法（GET、POST、PUT、DELETE等）定义端点
  • 参数：查询、路径、头部和Cookie参数，包含类型与约束
  • 请求体：带内容类型（如application/json）的负载模式
  • 响应：状态码、描述和响应模式
  • 示例：每个操作的请求与响应示例
  • 标签：对操作进行分组，便于组织与导航

REST API Documentation Patterns

REST API文档模式

Endpoint Documentation

端点文档

  • URL Pattern: Clear, RESTful URL structure (e.g., 
    /api/v1/users/{id}
    )
  • HTTP Method: Appropriate method for the operation (GET, POST, PUT, PATCH, DELETE)
  • Description: Clear explanation of what the endpoint does
  • Parameters: All parameters with types, required/optional status, and constraints
  • Request Body: Schema and examples for POST/PUT/PATCH operations
  • Responses: All possible responses with status codes, schemas, and examples
  • Authentication: Required authentication method and token format
  • URL模式：清晰的RESTful URL结构（例如：
    /api/v1/users/{id}
    ）
  • HTTP方法：为操作选择合适的方法（GET、POST、PUT、PATCH、DELETE）
  • 描述：清晰说明端点的功能
  • 参数：所有参数的类型、必填/可选状态及约束
  • 请求体：POST/PUT/PATCH操作的模式与示例
  • 响应：所有可能的响应，包含状态码、模式和示例
  • 认证：所需的认证方法与令牌格式

Response Documentation

响应文档

  • Success Responses: Document successful responses with examples
  • Error Responses: Document all error responses with codes and messages
  • Status Codes: Use appropriate HTTP status codes (200, 201, 400, 401, 404, 500, etc.)
  • Response Schema: JSON schema with field types, descriptions, and constraints
  • Response Examples: Multiple examples showing different scenarios
  • 成功响应：记录带示例的成功响应
  • 错误响应：记录所有带代码和消息的错误响应
  • 状态码：使用合适的HTTP状态码（200、201、400、401、404、500等）
  • 响应模式：包含字段类型、描述和约束的JSON模式
  • 响应示例：展示不同场景的多个示例

Pagination

分页

  • Pagination Parameters: Document page size, page number, offset, and limit
  • Response Metadata: Include total count, page count, and next/previous links
  • Pagination Examples: Show how to navigate through pages
  • Best Practices: Recommend default page sizes and maximum limits
  • 分页参数：记录页面大小、页码、偏移量和限制值
  • 响应元数据：包含总计数、页面总数以及上一页/下一页链接
  • 分页示例：展示如何在页面间导航
  • 最佳实践：推荐默认页面大小和最大限制值

GraphQL Documentation Practices

GraphQL文档实践

Schema Documentation

模式文档

  • Types: Document all object types, input types, and enums
  • Fields: Document each field with type, arguments, and description
  • Queries and Mutations: Document all available operations with parameters and return types
  • Subscriptions: Document real-time subscriptions with events and payloads
  • Directives: Document custom directives and their usage
  • 类型：记录所有对象类型、输入类型和枚举
  • 字段：记录每个字段的类型、参数和描述
  • 查询与变更：记录所有可用操作的参数和返回类型
  • 订阅：记录带事件和负载的实时订阅
  • 指令：记录自定义指令及其用法

Query Documentation

查询文档

  • Operation Name: Clear, descriptive operation names
  • Arguments: All arguments with types, required/optional status, and descriptions
  • Return Type: Document the return type structure
  • Examples: Provide query examples with variables
  • Error Handling: Document error responses and error types
  • 操作名称：清晰、描述性的操作名称
  • 参数：所有参数的类型、必填/可选状态和描述
  • 返回类型：记录返回类型的结构
  • 示例：提供带变量的查询示例
  • 错误处理：记录错误响应和错误类型

API Reference Documentation Structure

API参考文档结构

Organization

组织方式

  • Overview: High-level introduction to the API
  • Authentication: How to authenticate requests
  • Quick Start: Simple example to get started
  • Endpoints: Complete reference of all endpoints
  • Data Models: Common data structures and schemas
  • Error Codes: List of error codes and their meanings
  • Rate Limits: Rate limiting policies and best practices
  • Changelog: Version history and changes
  • 概述：API的高层介绍
  • 认证：如何对请求进行认证
  • 快速开始：快速上手的简单示例
  • 端点：所有端点的完整参考
  • 数据模型：通用的数据结构和模式
  • 错误码：错误码列表及其含义
  • 速率限制：速率限制策略与最佳实践
  • 更新日志：版本历史与变更记录

Endpoint Reference

端点参考

  • Grouping: Group endpoints by resource or functionality
  • Navigation: Clear navigation structure with breadcrumbs
  • Search: Searchable endpoint names and descriptions
  • Filtering: Filter by HTTP method, tag, or resource
  • Try It Out: Interactive testing capability
  • 分组：按资源或功能对端点进行分组
  • 导航：清晰的导航结构，包含面包屑
  • 搜索：可搜索端点名称和描述
  • 筛选：按HTTP方法、标签或资源进行筛选
  • 在线试用：交互式测试功能

Interactive API Documentation Tools

交互式API文档工具

Swagger UI

Swagger UI

  • Features: Interactive API exploration, "Try it out" functionality
  • Customization: Custom branding, themes, and plugins
  • Deployment: Can be deployed as static files or embedded
  • Authentication: Support for various auth methods (API key, OAuth, etc.)
  • Validation: Real-time request/response validation
  • 功能：交互式API探索、“在线试用”功能
  • 自定义：自定义品牌、主题和插件
  • 部署：可部署为静态文件或嵌入到应用中
  • 认证：支持多种认证方式（API密钥、OAuth等）
  • 验证：实时请求/响应验证

Redoc

Redoc

  • Features: Beautiful, responsive documentation from OpenAPI specs
  • Three-Panel Layout: Navigation, content, and code panels
  • Search: Full-text search across documentation
  • Mobile Friendly: Responsive design for mobile devices
  • Code Samples: Automatic code sample generation
  • 功能：基于OpenAPI规范生成美观、响应式的文档
  • 三面板布局：导航、内容和代码面板
  • 搜索：全文档全文搜索
  • 移动端适配：响应式设计，适配移动设备
  • 代码示例：自动生成代码示例

Stoplight

Stoplight

  • Features: API design, documentation, and testing platform
  • Visual Editor: Visual API designer with drag-and-drop
  • Mock Server: Automatic mock server generation
  • Testing: Built-in API testing and validation
  • Collaboration: Team collaboration features
  • 功能：API设计、文档和测试平台
  • 可视化编辑器：支持拖拽的可视化API设计器
  • 模拟服务器：自动生成模拟服务器
  • 测试：内置API测试与验证功能
  • 协作：团队协作功能

Code Examples and SDK Documentation

代码示例与SDK文档

Language Examples

多语言示例

  • Multiple Languages: Provide examples in JavaScript, Python, Java, cURL, etc.
  • Complete Examples: Full, runnable code samples
  • Error Handling: Include error handling in examples
  • Comments: Explain what the code does
  • Best Practices: Demonstrate best practices in examples
  • 多种语言：提供JavaScript、Python、Java、cURL等语言的示例
  • 完整示例：可直接运行的完整代码示例
  • 错误处理：示例中包含错误处理逻辑
  • 注释：解释代码的功能
  • 最佳实践：在示例中展示最佳实践

SDK Documentation

SDK文档

  • Installation: How to install and configure the SDK
  • Initialization: How to initialize the client
  • Authentication: How to authenticate with the SDK
  • Methods: Document all SDK methods with parameters and return types
  • Examples: Provide usage examples for common operations
  • Error Handling: How to handle errors and exceptions
  • 安装：如何安装和配置SDK
  • 初始化：如何初始化客户端
  • 认证：如何通过SDK进行认证
  • 方法：记录所有SDK方法的参数和返回类型
  • 示例：提供常见操作的使用示例
  • 错误处理：如何处理错误和异常

cURL Examples

cURL示例

  • Complete Commands: Full cURL commands with all options
  • Headers: Include all required headers
  • Authentication: Show authentication in cURL format
  • Request Body: Include request body for POST/PUT operations
  • Comments: Add comments to explain options
  • 完整命令：包含所有选项的完整cURL命令
  • 请求头：包含所有必填的请求头
  • 认证：展示cURL格式的认证方式
  • 请求体：包含POST/PUT操作的请求体
  • 注释：添加注释解释各选项的作用