api-documentation

name	api-documentation
description	Create comprehensive API documentation with examples, parameter descriptions, and interactive code samples

API Documentation Skill

Create professional API documentation that's clear, complete, and easy to use. This skill helps you generate well-structured API docs that serve both developers and non-technical stakeholders.

Purpose

This skill assists in generating and organizing API documentation that includes:

• Endpoint descriptions and HTTP methods
• Request and response examples
• Parameter documentation and validation rules
• Authentication and authorization details
• Error codes and troubleshooting
• Code samples in multiple languages
• Interactive examples

When to Use

Use this skill when you need to:

• Document REST or GraphQL APIs
• Create OpenAPI/Swagger specifications
• Generate SDK documentation
• Build internal API guides for your team
• Create developer portals
• Maintain up-to-date endpoint references
• Document webhook specifications

Key Features

1. Comprehensive Coverage - Document endpoints, parameters, responses, and errors
2. Multiple Formats - Generate OpenAPI 3.0, Markdown, or HTML documentation
3. Code Examples - Include samples in Python, JavaScript, cURL, and more
4. Interactive - Add runnable examples and API explorers
5. Organized - Use consistent structure and clear categorization
6. Version Control - Track API changes and deprecations
7. Team-Friendly - Easy for developers to contribute and update

Instructions

When using this skill:

1. Provide API Details - Give endpoint URLs, methods, and purposes
2. Document Parameters - Specify required/optional params, types, and constraints
3. Include Examples - Provide real-world request and response examples
4. Define Errors - List possible error codes and their meanings
5. Add Context - Explain authentication, rate limits, and usage patterns
6. Generate Output - Create documentation in your preferred format
7. Review & Iterate - Polish examples and clarify ambiguous sections

Guidelines

• Be Specific: Use concrete examples, not generic placeholders
• Stay Current: Keep documentation in sync with actual API behavior
• Think Like Users: Document common workflows and use cases
• Include Edge Cases: Highlight error conditions and limitations
• Use Standard Formats: Follow OpenAPI/AsyncAPI specifications where applicable
• Organize Logically: Group related endpoints and resources together
• Provide Multiple Paths: Show both basic and advanced usage patterns

Examples

Example 1: REST API Endpoint Documentation

Endpoint: Create User

POST /api/v1/users

Description: Creates a new user account with the provided information.

Authentication: Bearer Token (required)

Request:

{
  "email": "[e-mail]",
  "name": "John Doe",
  "role": "developer"
}

Response (201 Created):

{
  "id": "usr_12345",
  "email": "[e-mail]",
  "name": "John Doe",
  "role": "developer",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Response (400 Bad Request):

{
  "error": "INVALID_EMAIL",
  "message": "The provided email is invalid",
  "field": "email"
}

Example 2: Generate OpenAPI Specification

Input:

endpoints:
  - path: /api/products
    method: GET
    description: List all products
    parameters:
      - name: limit
        type: integer
        required: false
        default: 20

Output: OpenAPI 3.0 YAML specification with all endpoints, schemas, and examples properly formatted.

Documentation Templates

This skill includes templates for:

• endpoint-template.md - Single endpoint documentation
• api-overview.md - Complete API guide
• error-codes.md - Error reference
• authentication-guide.md - Auth patterns and flows

Code Examples

Helper scripts include:

• validate-api.py - Validate API endpoints against documentation
• generate-openapi.py - Convert specifications to OpenAPI format
• format-examples.py - Standardize code examples

Best Practices

• Document all endpoints before release
• Keep examples current and tested
• Include SDKs and client library links
• Provide sandbox/testing endpoints
• Maintain a changelog for API versions
• Support multiple authentication methods
• Include webhook documentation if applicable

Common API Documentation Patterns

Pattern	Use Case	Complexity
REST	General purpose APIs	Low
GraphQL	Complex data queries	High
gRPC	High-performance services	High
WebSocket	Real-time communication	Medium
OpenAPI	Standardized specification	Medium

Related Resources

• OpenAPI 3.0 Specification
• API Documentation Best Practices
• Code Example Templates
• Validation Tools

Support

For help with API documentation:

1. Review the examples above
2. Check the templates in assets/templates/
3. Consult the validation tools in scripts/
4. Reference the best practices guide