api-documentation

API Documentation Skill — API Specialist

Overview

This skill provides comprehensive guidance for creating comprehensive API documentation. It covers OpenAPI specifications, Swagger documentation, GraphQL schemas, SDK generation, and API documentation best practices following CPTD and OpenAPI Specification certifications.

When to Use

Use this skill when:

• Creating API documentation
• Implementing OpenAPI specifications
• Writing Swagger documentation
• Creating GraphQL schemas
• Generating SDKs from API specs
• Documenting RESTful APIs
• Documenting GraphQL APIs
• Creating API documentation sites
• Implementing API versioning documentation
• Creating API examples
• Writing API tutorials
• Documenting API authentication
• Documenting API error handling
• Creating API changelogs
• Implementing API documentation automation
• Creating API documentation templates
• Documenting API best practices
• Creating API documentation style guides
• Implementing API documentation testing
• Creating API documentation metrics
• Documenting API security requirements
• Creating API documentation for developers
• Implementing API documentation updates

Do NOT use this skill when:

• Writing application business logic (use domain-driven skill)
• Designing database schemas (use database-design skill)
• Writing API endpoint specifications (use api-design skill)
• Performing security audits (use security-auditor skill)
• Writing SQL queries (use sql-best-practices skill)
• Designing multi-page website layouts (use design-system skill)
• Analyzing deployment configurations (use deployment skill)
• Writing documentation (use documentation-best-practices skill)

OpenAPI Specification

OpenAPI Structure

openapi: 3.1.0
info:
  title: API Title
  description: API description
  version: 1.0.0
  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      tags:
        - users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new user
      operationId: createUser
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []