Back to Details

api-documenter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Documenter

API文档撰写助手

Purpose

用途

Provides expertise in creating clear, accurate, and developer-friendly API documentation. Specializes in OpenAPI 3.x specifications, GraphQL schema documentation, and interactive API references.
提供创建清晰、准确且对开发者友好的API文档的专业能力，擅长OpenAPI 3.x规范、GraphQL架构文档以及交互式API参考文档的制作。

When to Use

适用场景

  • Writing OpenAPI/Swagger specifications
  • Documenting REST API endpoints
  • Creating GraphQL schema documentation
  • Building interactive API references
  • Writing API getting-started guides
  • Documenting authentication flows
  • Creating SDK usage examples
  • 编写OpenAPI/Swagger规范
  • 记录REST API接口端点
  • 创建GraphQL架构文档
  • 构建交互式API参考文档
  • 编写API快速入门指南
  • 记录认证流程
  • 创建SDK使用示例

Quick Start

快速入门

Invoke this skill when:
  • Writing OpenAPI/Swagger specifications
  • Documenting REST API endpoints
  • Creating GraphQL schema documentation
  • Building interactive API references
  • Writing SDK usage examples
Do NOT invoke when:
  • Designing API architecture (use api-designer)
  • Writing user-facing product docs (use technical-writer)
  • Creating internal system docs (use document-writer)
  • Building the actual API (use backend developer skills)
以下场景可调用本技能：
  • 编写OpenAPI/Swagger规范
  • 记录REST API接口端点
  • 创建GraphQL架构文档
  • 构建交互式API参考文档
  • 创建SDK使用示例
以下场景请勿调用：
  • 设计API架构（请使用api-designer）
  • 编写面向用户的产品文档（请使用technical-writer）
  • 创建内部系统文档（请使用document-writer）
  • 构建实际API（请使用后端开发技能）

Decision Framework

决策框架

Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts
Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts

Core Workflows

核心工作流程

1. OpenAPI Specification Creation

1. OpenAPI规范创建

  1. Inventory all endpoints and methods
  2. Define request/response schemas
  3. Document parameters and headers
  4. Add authentication requirements
  5. Include example requests/responses
  6. Validate spec with linting tools
  1. 盘点所有接口端点及请求方法
  2. 定义请求/响应架构
  3. 记录参数和请求头
  4. 添加认证要求
  5. 包含请求/响应示例
  6. 使用代码检查工具验证规范

2. API Reference Documentation

2. API参考文档制作

  1. Group endpoints by resource or domain
  2. Write clear endpoint descriptions
  3. Document all parameters with types
  4. Provide request/response examples
  5. Include error codes and handling
  6. Add authentication examples
  1. 按资源或领域对接口端点进行分组
  2. 撰写清晰的接口端点描述
  3. 记录所有带类型的参数
  4. 提供请求/响应示例
  5. 包含错误码及处理方式
  6. 添加认证示例

3. API Getting Started Guide

3. API快速入门指南制作

  1. Explain authentication setup
  2. Show first API call example
  3. Walk through common use cases
  4. Include SDK installation steps
  5. Provide troubleshooting tips
  6. Link to full reference docs
  1. 说明认证设置步骤
  2. 展示首次API调用示例
  3. 引导讲解常见使用场景
  4. 包含SDK安装步骤
  5. 提供故障排查技巧
  6. 链接至完整参考文档

Best Practices

最佳实践

  • Use consistent terminology across all docs
  • Provide copy-pasteable code examples
  • Include both success and error responses
  • Version documentation with API versions
  • Test all code examples before publishing
  • Add rate limiting and quota information
  • 所有文档中使用统一术语
  • 提供可直接复制粘贴的代码示例
  • 同时包含成功和错误响应示例
  • 随API版本同步更新文档版本
  • 发布前测试所有代码示例
  • 添加速率限制和配额信息

Anti-Patterns

反模式

Anti-PatternProblemCorrect Approach
No examplesDevelopers guess at usageInclude request/response examples
Outdated docsBreaks developer trustAutomate doc generation from code
Missing errorsSurprise failures in productionDocument all error codes
Jargon-heavyConfuses new developersUse clear, simple language
No versioningBreaking changes unclearVersion docs with API
反模式问题正确做法
无示例开发者需猜测使用方式包含请求/响应示例
文档过时失去开发者信任从代码自动生成文档
缺少错误说明生产环境出现意外故障记录所有错误码
术语晦涩困扰新开发者使用清晰、简洁的语言
无版本控制破坏性变更不明确随API同步版本化文档