A Simple Analogy

Good API documentation is like a detailed recipe. It tells users exactly what they need, what happens, and what to expect.

---

Why Documentation?

• Usability: Users understand how to use API
• Adoption: Better adoption with clear docs
• Support: Reduce support tickets
• Contracts: Define expected behavior
• Onboarding: Help new developers quickly

---

Documentation Elements

Required for each endpoint:
- Description (what it does)
- Method (GET, POST, etc.)
- URL path
- Authentication needed
- Request parameters
- Request body example
- Response format
- Status codes
- Error responses
- Example requests/responses

---

OpenAPI Specification

openapi: 3.0.0
info:
  title: Order API
  version: 1.0.0
paths:
  /api/orders:
    get:
      summary: List orders
      description: Retrieve all orders with pagination
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized

---

Markdown Documentation

# Products API

## Get Product

Retrieve a single product by ID.

### Request

GET /api/products/{id}

### Parameters
- `id` (path, required): Product ID

### Response (200 OK)
```json
{
  "id": "prod-123",
  "name": "Widget",
  "price": 29.99,
  "stock": 100
}

Errors

• 404 Not Found: Product not found
• 400 Bad Request: Invalid product ID

---

## Code Comments

```csharp
/// <summary>
/// Retrieves a product by its unique identifier.
/// </summary>
/// <param name="id">The unique product identifier</param>
/// <returns>
/// A ProductDto containing the product details, or NotFound if product doesn't exist
/// </returns>
/// <response code="200">Product found and returned</response>
/// <response code="404">Product not found</response>
[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(ProductDto))]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ProductDto>> GetProduct(string id)
{
    var product = await _service.GetAsync(id);
    if (product == null) return NotFound();
    return Ok(product);
}

---

README Example

# My API

Quick start guide.

## Installation
```bash
dotnet build
dotnet run

Authentication

All requests require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -H "Authorization: Bearer xyz" \
  https://api.example.com/api/products

Rate Limits

• 1000 requests per hour
• Returns 429 Too Many Requests when exceeded

---

## Best Practices

1. **Keep updated:** Docs should match code
2. **Include examples:** Show real requests/responses
3. **Be clear:** Explain business logic
4. **Organize:** Group related endpoints
5. **Test links:** Verify examples work

---

## Related Concepts

- API versioning
- Change logs
- Migration guides
- Deprecation policies

---

## Summary

Document APIs thoroughly with clear descriptions, parameters, responses, and examples. Use OpenAPI standards and keep documentation in sync with code.