Agent Skills
› NeverSight/learn-skills.dev
› api-documenter
api-documenter
GitHub专注于创建OpenAPI/Swagger规范、GraphQL架构文档及RESTful API技术参考。涵盖端点记录、认证流程说明、SDK示例编写及交互式参考文档构建，确保文档准确、开发者友好且符合最佳实践。
Trigger Scenarios
编写OpenAPI或Swagger规范
记录REST API端点详情
创建GraphQL模式文档
构建交互式API参考手册
编写API入门指南或SDK使用示例
Install
npx skills add NeverSight/learn-skills.dev --skill api-documenter -g -y
SKILL.md
Frontmatter
{
"name": "api-documenter",
"description": "API documentation specialist who creates comprehensive OpenAPI\/Swagger specifications and technical documentation for RESTful APIs, GraphQL schemas, and microservices architectures. Use when writing API docs, creating OpenAPI specs, or documenting endpoints."
}
API Documenter
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.
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
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)
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
Core Workflows
1. OpenAPI Specification Creation
- Inventory all endpoints and methods
- Define request/response schemas
- Document parameters and headers
- Add authentication requirements
- Include example requests/responses
- Validate spec with linting tools
2. API Reference Documentation
- Group endpoints by resource or domain
- Write clear endpoint descriptions
- Document all parameters with types
- Provide request/response examples
- Include error codes and handling
- Add authentication examples
3. API Getting Started Guide
- Explain authentication setup
- Show first API call example
- Walk through common use cases
- Include SDK installation steps
- Provide troubleshooting tips
- Link to full reference docs
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
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| No examples | Developers guess at usage | Include request/response examples |
| Outdated docs | Breaks developer trust | Automate doc generation from code |
| Missing errors | Surprise failures in production | Document all error codes |
| Jargon-heavy | Confuses new developers | Use clear, simple language |
| No versioning | Breaking changes unclear | Version docs with API |
Version History
- e0220ca Current 2026-07-05 21:11
