Agent-Skills.md

Agent Skills: API Reference Documentation

Create comprehensive API reference documentation with OpenAPI/Swagger specs, REST endpoints, authentication, examples, and SDKs. Use when documenting REST APIs, GraphQL APIs, endpoint documentation, or OpenAPI specifications.

UncategorizedID: aj-geddes/useful-ai-prompts/api-reference-documentation

Repository

aj-geddes/useful-ai-prompts
aj-geddesLicense: MIT
607

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aj-geddes/useful-ai-prompts/tree/HEAD/skills/api-reference-documentation

Skill Files

Browse the full folder contents for api-reference-documentation.

Download Skill

Loading file tree…

skills/api-reference-documentation/SKILL.md

Skill Metadata

Name
api-reference-documentation
Description
>

API Reference Documentation

Table of Contents

Overview

Generate professional API documentation that developers can use to integrate with your API, including endpoint specifications, authentication, request/response examples, and interactive documentation.

When to Use

  • Documenting REST APIs
  • Creating OpenAPI/Swagger specifications
  • GraphQL API documentation
  • SDK and client library docs
  • API authentication guides
  • Rate limiting documentation
  • Webhook documentation
  • API versioning guides

Quick Start

Minimal working example:

openapi: 3.0.3
info:
  title: E-Commerce API
  description: |
    Complete API for managing e-commerce operations including products,
    orders, customers, and payments.

    ## Authentication
    All endpoints require Bearer token authentication. Include your API key
    in the Authorization header: `Authorization: Bearer YOUR_API_KEY`

    ## Rate Limiting
    - 1000 requests per hour for authenticated users
    - 100 requests per hour for unauthenticated requests

    ## Pagination
    List endpoints return paginated results with `page` and `limit` parameters.
  version: 2.0.0
  contact:
    name: API Support
    email: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

| Guide | Contents | |---|---| | OpenAPI Specification Example | openapi: 3.0.3 | | List Products | List Products |

Best Practices

✅ DO

  • Use OpenAPI 3.0+ specification
  • Include request/response examples for every endpoint
  • Document all query parameters and headers
  • Provide authentication examples
  • Include error response formats
  • Document rate limits and pagination
  • Use consistent naming conventions
  • Include SDK examples in multiple languages
  • Document webhook payloads
  • Provide interactive API explorer (Swagger UI)
  • Version your API documentation
  • Include migration guides for breaking changes

❌ DON'T

  • Skip error response documentation
  • Forget to document authentication
  • Use inconsistent terminology
  • Leave endpoints undocumented
  • Ignore deprecation notices
  • Skip versioning information