api-documentation skill

---
name: API Documentation
description: Creating comprehensive, interactive API documentation that enables developers to effectively integrate with your services using OpenAPI/Swagger, code examples, and best practices.
---

# API Documentation

## Overview

API documentation is critical for enabling developers to effectively integrate with your services. Well-documented APIs reduce integration time, minimize support requests, increase adoption, and improve developer satisfaction through clear examples, interactive tools, and comprehensive reference materials.

## Why This Matters

- **Reduces Support Burden**: Clear documentation answers common questions, reducing support tickets
- **Increases Developer Adoption**: Good documentation encourages developers to integrate with your API
- **Faster Integration**: Detailed examples and guides speed up development time
- **Consistent Quality**: Standardized documentation ensures consistent API usage across developers
- **Better Developer Experience**: Interactive documentation with try-it-now features improves developer satisfaction

---

## Core Concepts

### 1. OpenAPI Specification

Standard specification for documenting REST APIs:

- **OpenAPI 3.0**: Current version with enhanced features
- **Swagger 2.0**: Legacy version (still widely used)
- **YAML vs JSON**: Choose based on team preference and tooling
- **Structure**: Info, servers, paths, components, security

### 2. Documentation Generation

Tools for generating interactive documentation:

- **Swagger UI**: Try-it-out functionality, interactive testing
- **Redoc**: Beautiful, responsive documentation
- **Docusaurus**: Custom documentation sites
- **Stoplight**: Design-first approach with mock servers

### 3. Code Examples

Providing examples in multiple languages:

- **JavaScript/TypeScript**: Most common for web apps
- **Python**: Popular for data science and backend
- **Go**: Popular for microservices
- **Java**: Enterprise applications
- **cURL**: Universal command-line examples

### 4. Version Management

Strategies for API versioning:

- **URL Versioning**: `/api/v1/users`, `/api/v2/users`
- **Header Versioning**: `X-API-Version: 1`
- **Content Negotiation**: `Accept: application/vnd.api.v1+json`

### 5. Changelog Tracking

Documenting API changes:

- **Semantic Versioning**: MAJOR.MINOR.PATCH
- **Breaking Changes**: Clearly mark deprecations and removals
- **New Features**: Highlight additions and enhancements
- **Bug Fixes**: Document resolved issues

### 6. Interactive Features

Enhancing documentation usability:

- **Try-It-Now**: In-browser API testing
- **Authentication**: Built-in OAuth2 flow
- **Request Builder**: Visual request construction
- **Response Examples**: Sample responses for all endpoints
- **Error Documentation**: Detailed error codes and messages

## Quick Start

1. **Choose Specification**: Select OpenAPI 3.0 or Swagger 2.0 based on your needs
2. **Design OpenAPI Spec**: Create YAML or JSON specification with all endpoints
3. **Select Documentation Tool**: Choose Swagger UI, Redoc, or Docusaurus based on requirements
4. **Generate Documentation**: Build interactive documentation from specification
5. **Add Code Examples**: Provide examples in multiple programming languages
6. **Implement Authentication**: Configure OAuth2 or API key authentication for try-it-out
7. **Set Up Hosting**: Deploy to GitHub Pages, Vercel, or Netlify
8. **Configure Search**: Enable search functionality for easy navigation
9. **Set Up Analytics**: Track documentation usage with Google Analytics
10. **Maintenance Plan**: Establish process for keeping documentation in sync with API changes

```yaml
# openapi.yaml example
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API documentation example
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://api-staging.example.com/v1
    description: Staging server
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
```

## Production Checklist

- [ ] OpenAPI specification complete (all endpoints documented)
- [ ] Interactive documentation deployed (Swagger UI/Redoc)
- [ ] Code examples provided in multiple languages
- [ ] Authentication configured for try-it-out
- [ ] Error responses documented with codes and explanations
- [ ] Versioning strategy implemented
- [ ] Changelog maintained for all changes
- [ ] Search functionality enabled
- [ ] Analytics configured (Google Analytics, etc.)
- [ ] Documentation tested on multiple browsers
- [ ] Performance optimized (<2s page load time)
- [ ] Mobile responsive design
- [ ] Accessibility compliance (WCAG 2.1 AA)
- [ ] SSL/TLS enabled
- [ ] CDN configured for static assets
- [ ] CI/CD pipeline for documentation updates
- [ ] Maintenance process established
- [ ] Support contact information available

## Anti-patterns

1. **Outdated Documentation**: Documentation not synced with API changes causes confusion and integration failures
2. **Missing Examples**: No code examples make integration difficult
3. **No Version Management**: Unclear versioning leads to breaking changes for existing users
4. **No Error Documentation**: Undocumented errors cause debugging difficulties
5. **Poor Navigation**: Hard-to-navigate documentation frustrates users
6. **No Authentication**: Try-it-out doesn't work without proper authentication setup
7. **Over-Engineering**: Too complex documentation systems become hard to maintain
8. **No Analytics**: Without usage tracking, you can't measure documentation effectiveness
9. **Inconsistent Terminology**: Mixed terminology confuses users
10. **No Search**: Missing search functionality makes finding information difficult

## Integration Points

- **OpenAPI Specification**: [https://swagger.io/specification/](https://swagger.io/specification/)
- **Swagger UI**: [https://github.com/swagger-api/swagger-ui](https://github.com/swagger-api/swagger-ui)
- **Redoc**: [https://github.com/Redocly/redoc](https://github.com/Redocly/redoc)
- **Docusaurus**: [https://docusaurus.io/](https://docusaurus.io/)
- **Stoplight**: [https://stoplight.io/](https://stoplight.io/)
- **GitHub Pages**: Free hosting for static documentation
- **Vercel**: Hosting platform with CI/CD
- **Netlify**: Hosting platform with automatic deployments

## Further Reading

- [OpenAPI Specification](https://swagger.io/specification/)
- [Writing Good Documentation](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/)
- [API Documentation Best Practices](https://blog.restcase.com/7-best-practices-for-api-documentation/)
- [Technical Writing Style Guide](https://developers.google.com/tech-writing/one)
- [Documentation Driven Development](https://www.writethedocs.org/guide/docs-as-code/)