API Documentation Skill

API Documentation Skill

Purpose

Create comprehensive API documentation.

OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  description: |
    API description with **markdown** support.

    ## Authentication
    Use Bearer tokens.

servers:
  - url: https://api.example.com
    description: Production

paths:
  /​users:
    get:
      operationId: listUsers
      summary: List all users
      tags: [Users]
      parameters:
        - $ref: '#/​components/​parameters/​PageParam'
      responses:
        '200':
          description: Success
          content:
            application/​json:
              schema:
                $ref: '#/​components/​schemas/​UserList'

components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

Code Examples

Multiple Languages

# In OpenAPI
paths:
  /​users:
    post:
      x-codeSamples:
        - lang: curl
          source: |
            curl -X POST https://api.example.com/users \
              -H "Authorization: Bearer TOKEN" \
              -d '{"name": "John"}'
        - lang: python
          source: |
            import requests
            requests.post('https://api.example.com/users',
              headers={'Authorization': 'Bearer TOKEN'},
              json={'name': 'John'})
        - lang: javascript
          source: |
            await fetch('https://api.example.com/users', {
              method: 'POST',
              headers: { 'Authorization': 'Bearer TOKEN' },
              body: JSON.stringify({ name: 'John' })
            });

SDK Generation

# Generate TypeScript SDK
npx @openapitools/​openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./​sdk

# Generate Python SDK
openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./​sdk-python

Changelog Format

# Changelog

## [1.2.0] - 2024-12-30

### Added
- `GET /​users/​export` endpoint

### Changed
- `POST /​users` now returns 201

### Deprecated
- `GET /​users/:id/​profile` (use `/​users/:id`)

### Fixed
- Pagination cursor encoding

---

Unit Test Template

import { validate } from '@apidevtools/​swagger-parser';

describe('OpenAPI Spec', () => {
  it('should be valid OpenAPI 3.1', async () => {
    const api = await validate('./​openapi.yaml');
    expect(api.openapi).toMatch(/^3\.1\./);
  });

  it('should have examples for all endpoints', async () => {
    const api = await validate('./​openapi.yaml');
    Object.values(api.paths).forEach(path => {
      Object.values(path).forEach(operation => {
        if (operation.responses?.['200']) {
          expect(operation.responses['200'].content)
            .toHaveProperty('application/​json.examples');
        }
      });
    });
  });
});

---

Troubleshooting

---

Quality Checklist

• OpenAPI spec validates
• All endpoints documented
• Request/​response examples
• Error responses documented
• Authentication explained
• SDKs generated and tested