Api Reference Documentation

API Reference Documentation

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

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:

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

List Products

List Products

Retrieve a paginated list of products.

Endpoint: GET /products

Query Parameters:

Example Request:

curl -X GET "https://api.example.com/v2/products?page=1&limit=20&category=electronics" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Wireless Headphones",
      "description": "Premium noise-cancelling wireless headphones",
      "price": 299.99,
      "sku": "WH-1000XM5",
      "category": "electronics",
      "stock": 150,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Responses:

OpenAPI Specification 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

servers:
  - url: https://api.example.com/v2
    description: Production server
  - url: https://staging-api.example.com/v2
    description: Staging server
  - url: http://localhost:3000/v2
    description: Local development

tags:
  - name: Products
    description: Product management operations
  - name: Orders
    description: Order processing and tracking
  - name: Customers
    description: Customer management
  - name: Authentication
    description: Authentication endpoints

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login endpoint

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for server-to-server authentication

  schemas:
    Product:
      type: object
      required:
        - name
        - price
        - sku
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          minLength: 1
          maxLength: 200
          example: "Wireless Headphones"
        description:
          type: string
          maxLength: 2000
          example: "Premium noise-cancelling wireless headphones"
        price:
          type: number
          format: float
          minimum: 0
          example: 299.99
        sku:
          type: string
          pattern: "^[A-Z0-9-]+$"
          example: "WH-1000XM5"
        category:
          type: string
          enum: [electronics, clothing, books, home, sports]
          example: "electronics"
        stock:
          type: integer
          minimum: 0
          example: 150
        images:
          type: array
          items:
            type: string
            format: uri
          example:
            - "https://cdn.example.com/products/wh-1000xm5-1.jpg"
            - "https://cdn.example.com/products/wh-1000xm5-2.jpg"
        tags:
          type: array
          items:
            type: string
          example: ["wireless", "bluetooth", "noise-cancelling"]
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    Order:
      type: object
      required:
        - customerId
        - items
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        customerId:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/OrderItem"
        status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          default: pending
        totalAmount:
          type: number
          format: float
          readOnly: true
        shippingAddress:
          $ref: "#/components/schemas/Address"
        createdAt:
          type: string
          format: date-time
          readOnly: true

    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
        price:
          type: number
          format: float
          readOnly: true

    Address:
      type: object
      required:
        - street
        - city
        - country
        - postalCode
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

    PaginatedProducts:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: "UNAUTHORIZED"
            message: "Authentication token is missing or invalid"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: "NOT_FOUND"
            message: "The requested resource was not found"

paths:
  /products:
    get:
      summary: List products
      description: Retrieve a paginated list of products with optional filtering
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
        - name: maxPrice
          in: query
          schema:
            type: number
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedProducts"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      summary: Create product
      description: Create a new product
      tags:
        - Products
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Product"
            examples:
              headphones:
                summary: Wireless headphones
                value:
                  name: "Wireless Headphones"
                  description: "Premium noise-cancelling"
                  price: 299.99
                  sku: "WH-1000XM5"
                  category: "electronics"
                  stock: 150
      responses:
        "201":
          description: Product created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /products/{productId}:
    get:
      summary: Get product
      description: Retrieve a specific product by ID
      tags:
        - Products
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Product found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "404":
          $ref: "#/components/responses/NotFound"