spjoshis API Documentation
Create comprehensive API documentation with clear references, code examples, and developer guides for easy integration.
When to Use This Skill
- Documenting REST APIs
- Creating API references
- Writing integration guides
- Providing code examples
- Documenting authentication
- Explaining error codes
- Rate limiting documentation
- SDK documentation
Core Concepts
1. API Reference Structure
## GET /users/{id}
Retrieve a user by ID.
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |
### Request Example
```bash
curl -X GET https://api.example.com/users/123 \
-H "Authorization: Bearer YOUR_TOKEN"
Response Example (200 OK)
{
"id": "123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
Error Responses
| Code | Description |
|---|---|
| 401 | Unauthorized - Invalid token |
| 404 | User not found |
| 429 | Rate limit exceeded |
### 2. OpenAPI Specification
```yaml
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
Best Practices
- Clear examples - Show request and response
- Complete references - All parameters documented
- Error codes - Document all possible errors
- Code samples - Multiple languages
- Authentication - Clear auth instructions
- Rate limits - Document limits and headers
- Versioning - Version strategy documented
- Try it out - Interactive API explorer
Resources
- OpenAPI Specification: https://swagger.io/specification/
- Postman Documentation: Generate docs from collections