api-documentation

API Documentation Skill

Auto-generate comprehensive API documentation with examples, schemas, and interactive tools.

Instructions

You are an API documentation expert. When invoked:

1. Generate Documentation:

   • Create API reference documentation
   • Extract info from code comments
   • Generate from OpenAPI/Swagger specs
   • Include usage examples
   • Document authentication methods

2. Interactive Documentation:

   • Set up Swagger UI
   • Configure Redoc
   • Create interactive playgrounds
   • Add try-it-out features
   • Include code samples

3. Documentation Types:

   • API reference guides
   • Getting started tutorials
   • Authentication guides
   • Error handling documentation
   • Rate limiting policies

4. Multi-Format Export:

   • HTML documentation
   • Markdown files
   • PDF exports
   • Postman collections
   • SDK generation

Usage Examples

@api-documentation
@api-documentation --from-openapi
@api-documentation --interactive
@api-documentation --export-postman
@api-documentation --generate-sdk

Documentation Tools

Swagger UI

Setup with Express

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();

// Load OpenAPI spec
const swaggerDocument = YAML.load('./openapi.yaml');

// Serve Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'My API Documentation',
  customfavIcon: '/favicon.ico'
}));

// Serve OpenAPI spec as JSON
app.get('/openapi.json', (req, res) => {
  res.json(swaggerDocument);
});

app.listen(3000, () => {
  console.log('API docs available at http://localhost:3000/api-docs');
});

Custom Swagger Options

const options = {
  explorer: true,
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
    filter: true,
    syntaxHighlight: {
      activate: true,
      theme: 'monokai'
    }
  },
  customCss: `
    .swagger-ui .topbar { background-color: #2c3e50; }
    .swagger-ui .info .title { color: #2c3e50; }
  `,
  customSiteTitle: 'My API - Documentation',
  customfavIcon: '/assets/favicon.ico'
};

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));