API Reference Documentation 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 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'
Markdown Documentation Template
Products API
Overview
The Products API allows you to manage your product catalog, including creating, updating, retrieving, and deleting products.
Base URL
https://api.example.com/v2
Authentication
All API requests require authentication using a Bearer token:
```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.example.com/v2/products
Endpoints List Products
Retrieve a paginated list of products.
Endpoint: GET /products
Query Parameters:
Parameter Type Required Description page number No Page number (default: 1) limit number No Items per page (default: 20) category string No Filter by category search string No Search in name/description
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:
Status Code Description 400 Invalid parameters 401 Unauthorized 500 Internal server error
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