api-documentation-writer

name	api-documentation-writer
description	Expert guide for writing comprehensive API documentation including OpenAPI specs, endpoint references, authentication guides, and code examples. Use when documenting APIs, creating developer portals, or improving API discoverability.

2024-01-01 - v1.1.0

Added

• Webhook support for user events
• status filter on GET /users

Security

• API keys now support IP allowlisting

## Interactive Documentation

### Swagger UI Configuration

```javascript
// swagger-config.js
const swaggerUiOptions = {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'API Documentation',
  customfavIcon: '/favicon.ico',
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
    filter: true,
    tryItOutEnabled: true,
  },
};

Redoc Configuration

# redoc.yaml
x-tagGroups:
  - name: Getting Started
    tags:
      - Authentication
  - name: Core Resources
    tags:
      - Users
      - Items
  - name: Utilities
    tags:
      - Webhooks
      - Health


## Core Workflows

### Workflow 1: Primary Action
1. Analyze the input and context
2. Validate prerequisites are met
3. Execute the core operation
4. Verify the output meets expectations
5. Report results

x-logo:
  url: 'https://example.com/logo.png'
  altText: 'API Logo'

Documentation Checklist

Per Endpoint

• Summary (one line)
• Description (detailed explanation)
• All parameters documented with types and examples
• All response codes with examples
• Error codes with remediation steps
• Code examples in at least 2 languages
• Authentication requirements stated

Overall API

• Getting started guide
• Authentication guide with examples
• Rate limiting documentation
• Pagination patterns
• Error handling guide
• Changelog maintained
• Versioning strategy documented
• SDK/library links

Developer Experience

• Interactive "Try It" functionality
• Copy-paste ready examples
• Consistent terminology
• Search functionality
• Mobile-friendly rendering

Tools Integration

Generate from Code

# From Express/Node.js routes
npx swagger-jsdoc -d swaggerDef.js -o openapi.yaml

# From TypeScript types
npx openapi-typescript-codegen --input openapi.yaml --output ./sdk

Validate OpenAPI

# Validate spec
npx @redocly/cli lint openapi.yaml

# Preview documentation
npx @redocly/cli preview-docs openapi.yaml

When to Use This Skill

Invoke this skill when:

• Creating new API documentation from scratch
• Adding documentation for new endpoints
• Writing OpenAPI/Swagger specifications
• Creating code examples for multiple languages
• Documenting authentication flows
• Building developer portals
• Improving existing API documentation
• Setting up interactive documentation (Swagger UI, Redoc)