Creating API Documentation

In this lesson we walk through producing clear, machine-readable API documentation for a small FastAPI service. The example demonstrates how to:

define request/response shapes with Pydantic,
provide human-readable docstrings that appear in generated docs,
expose structured OpenAPI metadata using FastAPI decorator parameters,
manage a simple SQLite data source safely with a context manager,
validate inputs and return meaningful HTTP responses.

A presentation slide titled "Creating API Documentation" with a dark blue curved shape on the right. The word "Demo" appears in large blue text over the dark area.

FastAPI automatically generates interactive API documentation (Swagger UI at /docs and ReDoc at /redoc) from your path operations, Pydantic models, and docstrings. Use explicit Pydantic models, decorator parameters like response_model and responses, and clear docstrings to produce the best developer experience.

FastAPI exposes automatic documentation at /docs (Swagger UI) and /redoc (ReDoc). Use clear Pydantic models and enriched docstrings for descriptions. To produce structured OpenAPI metadata (tags, response schemas, examples), prefer using FastAPI’s parameters such as response_model, responses, tags, or app.openapi customization rather than relying on free-form YAML inside docstrings.

Example FastAPI application (concise and documented)

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
import sqlite3
from typing import List, Dict, Iterator
from contextlib import contextmanager
from pathlib import Path

app = FastAPI(title="Fake Data API")


class DataRequest(BaseModel):
    count: int = Field(..., ge=1, le=1000, description="Number of fake data entries to retrieve (1-1000)")


BASE_DIR = Path(__file__).resolve().parent
DATA_DIR = BASE_DIR / "data" / "db"
DB_PATH = DATA_DIR / "fakedata.db"

# Create data directory if it doesn't exist
DATA_DIR.mkdir(parents=True, exist_ok=True)


@contextmanager
def get_db_connection() -> Iterator[sqlite3.Connection]:
    """
    Create and manage a SQLite database connection as a context manager.

    This yields an sqlite3.Connection configured with `sqlite3.Row` for
    dict-like access to query results, and ensures the connection is
    closed when the context manager exits.

    Usage:
    >>> with get_db_connection() as conn:
    ...     cursor = conn.cursor()
    ...     cursor.execute("SELECT 1")
    ...     cursor.fetchall()

    Yields:
        sqlite3.Connection: Active SQLite connection.

    Raises:
        sqlite3.Error: If connecting to the database fails.
    """
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    try:
        yield conn
    finally:
        conn.close()


def fetch_fake_data(count: int) -> List[Dict]:
    """
    Retrieve `count` rows of fake data from the database.

    Args:
        count: Number of rows to return (1-1000).

    Returns:
        List[Dict]: List of rows as dictionaries.

    Raises:
        sqlite3.Error: If a database error occurs.
        ValueError: If `count` is out of allowed range.
    """
    if count < 1 or count > 1000:
        raise ValueError("count must be between 1 and 1000")

    with get_db_connection() as conn:
        cursor = conn.cursor()
        cursor.execute(
            """
            SELECT first_name, last_name, email_address, age, city, occupation
            FROM fake_data
            ORDER BY RANDOM()
            LIMIT ?
            """,
            (count,),
        )
        rows = cursor.fetchall()
        return [dict(row) for row in rows]


@app.post("/api/v1/getfakedata", response_model=List[Dict])
async def get_fake_data(request: DataRequest):
    """
    Generate fake personal data entries from the database.

    ---
    tags:
      - Fake Data API
      - Data Generation
    summary: Retrieve randomly generated personal data entries
    description: |
      Endpoint generates and returns randomly selected fake personal data entries
      from a pre-populated SQLite database. Each entry contains fields including
      name, email, age, city, and occupation. Limit 1-1000 per request.

    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
                minimum: 1
                maximum: 1000
                example: 2

    responses:
      '200':
        description: Successfully retrieved fake data entries
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  first_name: { type: string, example: "John" }
                  last_name: { type: string, example: "Doe" }
                  email_address: { type: string, format: email, example: "john.doe@example.com" }
                  age: { type: integer, example: 30 }
                  city: { type: string, example: "New York" }
                  occupation: { type: string, example: "Engineer" }
      '400':
        description: Invalid request parameters
        content:
          application/json:
            example:
              detail: "Count must be between 1 and 1000"
      '404':
        description: No data found in database
        content:
          application/json:
            example:
              detail: "No data entries found in database"
      '500':
        description: Internal server error
        content:
          application/json:
            example:
              detail: "Internal server error occurred"
    """
    count = request.count

    if count <= 0:
        raise HTTPException(status_code=400, detail="Count must be greater than 0")
    if count > 1000:
        raise HTTPException(status_code=400, detail="Count must not exceed 1000")

    try:
        results = fetch_fake_data(count)
        if not results:
            raise HTTPException(status_code=404, detail="No data entries found in database")
        return results
    except sqlite3.Error as exc:
        raise HTTPException(status_code=500, detail=str(exc))


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

Example request and response

# Example request (curl)
curl -X POST "http://localhost:8000/api/v1/getfakedata" \
  -H "Content-Type: application/json" \
  -d '{"count": 2}'

// Example successful response (200)
[
  {
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john.doe@example.com",
    "age": 30,
    "city": "New York",
    "occupation": "Engineer"
  },
  {
    "first_name": "Jane",
    "last_name": "Smith",
    "email_address": "jane.smith@example.com",
    "age": 25,
    "city": "Boston",
    "occupation": "Designer"
  }
]

Running the application (console output example)

INFO:     Started server process [XXXXX]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Quick reference

Resource	Path / Example	Notes
Swagger UI	`/docs`	Interactive UI to explore endpoints and schemas.
ReDoc	`/redoc`	Alternative static docs UI generated from OpenAPI.
OpenAPI JSON	`/openapi.json`	Export and validate with external tools.
Start app	`uvicorn main:app --reload`	Use `--reload` for development.
Request example	`curl -X POST ".../getfakedata" -d '{"count": 2}'`	Content-Type: `application/json`.

Tips to improve generated documentation

Use Pydantic models for both requests and responses. Add Field constraints and descriptions — FastAPI converts these into OpenAPI schemas and examples.
Include response_model, responses, and tags in your route decorators to make structured OpenAPI fields explicit.
Docstrings are included as descriptive text in the generated docs. For machine-readable metadata prefer decorator parameters or app.openapi() customization.
Provide example response bodies and document common HTTP errors (400/404/500) so API consumers know what to expect.
Validate the generated OpenAPI JSON (/openapi.json) with external linters or Swagger tools to ensure compliance and catch missing schemas.

Do not use a plain SQLite file or an unprotected database path in production without proper access controls and backups. For production workloads, prefer managed databases, connection pooling, and secrets management. Also avoid exposing internal debug information in HTTP error responses.

Links and references

FastAPI Docs: https://fastapi.tiangolo.com/
Pydantic Docs: https://pydantic-docs.helpmanual.io/
Uvicorn: https://www.uvicorn.org/
OpenAPI Specification: https://spec.openapis.org/
SQLite: https://sqlite.org/index.html

Further workflow tip Use tools like conversational code assistants (for example, GitHub Copilot or chat models) to iterate on docstrings, parameter descriptions, and example responses. Treat these tools as reviewers that suggest clearer summaries, improved parameter docs, and additional edge cases — but always review the generated /docs and /redoc output manually and validate the openapi.json before shipping. This concludes the lesson. Thank you for reading.

Introduction

GitHub Copilot Basics

Prompt Engineering with Copilot

Advanced Features

Management of GitHub Copilot

Using Copilot Efficiently

Creating API Documentation

Watch Video