What is OpenAPI 3.0 and why use it?

OpenAPI 3.0 is a standard for describing REST APIs, including endpoints, parameters, schemas, and security. It serves as a single source of truth for docs and SDK generation.

How do interactive docs work?

Interactive docs render from the OpenAPI spec using tools like Swagger UI or Redoc, allowing developers to try requests, view responses, and inspect schemas directly in the browser.

How should I keep docs up-to-date with API changes?

Version the OpenAPI spec, maintain migration guides, and automate doc generation in CI/CD so updates are released alongside code changes.

api-reference-documentation

Scanned

npx machina-cli add skill secondsky/claude-skills/api-reference-documentation --openclaw

Files (1)

SKILL.md

2.2 KB

API Reference Documentation

Create comprehensive API documentation for developer integration.

OpenAPI 3.0 Specification

openapi: 3.0.3
info:
  title: E-Commerce API
  version: 1.0.0
  description: API for managing products and orders
  contact:
    email: api@example.com

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

security:
  - bearerAuth: []

paths:
  /products:
    get:
      summary: List products
      tags: [Products]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id: { type: string, format: uuid }
        name: { type: string, maxLength: 200 }
        price: { type: number, minimum: 0 }
        description: { type: string }

Documentation Checklist

All endpoints documented with examples
Authentication methods explained
Error responses specified
Rate limits documented
Pagination explained
Webhooks documented (if applicable)
SDK examples in multiple languages

Best Practices

Use OpenAPI 3.0+ specification
Include request/response examples
Document all parameters and headers
Provide authentication examples
Enable interactive API exploration
Maintain version documentation
Include migration guides for breaking changes

Tools

Swagger Editor / Swagger UI
Redoc
Postman Documentation
Stoplight

Source

git clone https://github.com/secondsky/claude-skills/blob/main/plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.md

View on GitHub

Overview

Generates professional API documentation from OpenAPI 3.0 specs. It documents endpoints, parameters, authentication, and error responses, making it ideal for REST APIs, SDK references, and developer portals.

How This Skill Works

The skill ingests an OpenAPI 3.0 document (paths, components, and security schemes) to generate developer-friendly docs with request/response examples. It supports interactive explorers like Swagger UI or Redoc and produces SDK references across languages, ensuring every endpoint, header, parameter, and error schema is covered.

When to Use It

Document REST APIs with endpoints, parameters, and error schemas from an OpenAPI 3.0 spec.
Create SDK references in multiple languages (JS, Python, etc.) based on the OpenAPI definitions.
Build a developer portal with interactive API exploration for developers.
Publish versioned API docs and migration guides for breaking changes.
Explain authentication methods (e.g., bearer JWT) and rate limits in the docs.

Quick Start

Step 1: Start with an OpenAPI 3.0 spec (example in the SKILL.md shows endpoints, security, and schemas).
Step 2: Generate docs using Swagger UI or Redoc, including authentication and example requests/responses.
Step 3: Publish to a developer portal and add SDK references; implement versioning and migration notes.

Best Practices

Use OpenAPI 3.0+ specifications as the single source of truth.
Include request/response examples for every endpoint and method.
Document all parameters, headers, and their possible values.
Provide authentication examples and security scheme details.
Enable interactive API exploration with Swagger UI or Redoc.

Example Use Cases

Documenting an e-commerce REST API with /products, limit and category query params, and a Product schema.
Building a developer portal for a payments API that uses bearerAuth (JWT) and detailed error responses.
Generating JS and Python SDK references from the OpenAPI spec to accelerate integration.
Publishing interactive docs via Swagger UI/Redoc for a production API and a staging environment.
Maintaining versioned docs (e.g., v1.0) with migration guides for breaking changes.

Frequently Asked Questions

Add this skill to your agents