api-documentation

API Documentation

Generate comprehensive, interactive API documentation for multiple API protocols including REST/HTTP, gRPC, GraphQL, and RPC. This skill helps create documentation that is accurate, up-to-date, and useful for both developers and consumers.

When to use me

Use this skill when:

• You need to document APIs for internal or external consumers
• You have multiple API protocols (REST, gRPC, GraphQL, RPC) that need consistent documentation
• You want to generate documentation from code or API definitions automatically
• You need interactive documentation with testing capabilities
• You're preparing API documentation for public release or developer portals
• You need to maintain documentation consistency across multiple API versions
• You want to improve API discoverability and usability

What I do

• Multi-protocol support: Generate documentation for REST/HTTP, gRPC, GraphQL, and RPC APIs
• Code-first documentation: Extract documentation from code annotations, OpenAPI/Swagger, Protobuf, GraphQL schemas
• Interactive examples: Create executable API examples with testing capabilities
• Version management: Handle multiple API versions with migration guides
• Consistency checking: Ensure consistency between API implementation and documentation
• Documentation generation: Generate HTML, Markdown, PDF, and interactive API consoles
• Authentication documentation: Document authentication methods (OAuth, API keys, JWT)
• Error handling documentation: Document error codes, messages, and troubleshooting
• Rate limiting documentation: Document rate limits, quotas, and usage policies

Examples

# Generate OpenAPI documentation from code
./scripts/analyze-api-docs.sh --source src/ --format openapi

# Generate gRPC documentation from Protobuf files
./scripts/analyze-api-docs.sh --source proto/ --format grpc

# Generate GraphQL schema documentation
./scripts/analyze-api-docs.sh --source schema.graphql --format graphql

# Generate comprehensive API portal
./scripts/analyze-api-docs.sh --portal --output docs/api-portal

# Check documentation consistency
./scripts/analyze-api-docs.sh --consistency-check --api implementations/

Output format

API Documentation Analysis
─────────────────────────────────────
API Protocol: REST/HTTP
Source Files: 42
Endpoints Documented: 127/142 (89%)

DOCUMENTATION QUALITY METRICS:
───────────────────────────────
✅ Complete: Authentication documented (OAuth 2.0, API keys)
✅ Complete: Error responses documented (25 error codes)
✅ Complete: Request/response examples provided
⚠️ Needs Improvement: Rate limiting documentation missing
⚠️ Needs Improvement: 15 endpoints missing parameter descriptions
❌ Missing: Version migration guide for v1 → v2

API DISCOVERABILITY:
────────────────────
• Endpoints grouped by resource (Users, Products, Orders)
• Search functionality available
• Interactive testing console enabled
• SDK generation for 5 languages (JavaScript, Python, Go, Java, C#)

MULTI-PROTOCOL ANALYSIS:
────────────────────────
REST/HTTP APIs: 142 endpoints
  • OpenAPI specification: Complete
  • Interactive docs: Available via Swagger UI
  • Testing examples: 85%

gRPC APIs: 28 services
  • Protobuf documentation: Complete
  • gRPC reflection: Enabled
  • Client libraries: Generated for 3 languages

GraphQL APIs: 1 schema
  • GraphQL schema: Documented
  • GraphiQL interface: Available
  • Queries/Mutations: 47 operations documented

RPC APIs: 12 methods
  • JSON-RPC documentation: Partial
  • WebSocket support: Documented
  • Binary protocols: Not documented

CONSISTENCY ISSUES (3):
────────────────────────
1. Endpoint /api/v1/users/{id}/profile missing from OpenAPI spec
2. gRPC service "PaymentService" missing authentication documentation
3. GraphQL field "Product.inventory" description inconsistent with REST API

RECOMMENDATIONS:
────────────────
1. HIGH PRIORITY: Document rate limiting policies for all endpoints
2. HIGH PRIORITY: Add version migration guide for upcoming v2 release
3. MEDIUM PRIORITY: Complete JSON-RPC documentation for remaining 5 methods
4. MEDIUM PRIORITY: Generate SDKs for additional languages (Ruby, PHP, Swift)
5. LOW PRIORITY: Add deprecation notices for endpoints scheduled for removal

GENERATED ARTIFACTS:
────────────────────
• OpenAPI 3.0 specification: openapi.yaml
• Interactive API console: docs/api-console/index.html
• Client SDKs: sdk/javascript/, sdk/python/, sdk/go/
• API reference PDF: docs/api-reference.pdf
• Postman collection: docs/postman-collection.json
• cURL examples: docs/curl-examples.md

Notes

• Documentation should be generated as close to the code as possible
• Interactive documentation increases API adoption and reduces support requests
• Consistency between API implementation and documentation is critical
• Consider documentation as part of the API development lifecycle
• Different API protocols may require different documentation approaches
• Version management helps consumers migrate between API versions
• Authentication and error handling are the most commonly referenced sections
• Regular documentation reviews help maintain accuracy and completeness