FastAPI API Documentation Tools Comparison

A comparison project evaluating three popular API documentation tools (Swagger UI, Redoc, and Scalar) for FastAPI applications. This project explores their features, usability, and production applicability.

Project Goals

• Compare Swagger UI, Redoc, and Scalar side-by-side
• Evaluate interactive features vs. read-only documentation
• Assess design, usability, and production readiness
• Determine best documentation tool for different use cases

Tech Stack

• Python: 3.11+
• FastAPI: Latest version
• Documentation Tools:
  • Swagger UI: Interactive API documentation with "Try it out"
  • Redoc: Clean, read-only 3-panel documentation
  • Scalar: Modern documentation combining beautiful design with interactivity
• uv: Fast Python package manager
• Ruff: Python linter and formatter
• Pyright: Static type checker

Quick Start

Prerequisites

• Python 3.11 or higher
• uv installed

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation & Running

# 1. Clone the repository
git clone https://github.com/yourusername/fastapi-docs-comparison.git
cd fastapi-docs-comparison

# 2. Install dependencies (using Makefile)
make install

# 3. Run development server
make run

Without Makefile (if Make is not available):

uv sync                              # Install dependencies
uv run uvicorn src.main:app --reload # Run server

Access Documentation

Once the server starts, you can compare all three documentation tools:

• Swagger UI: http://localhost:8000/docs - Interactive API testing with "Try it out"
• Redoc: http://localhost:8000/redoc - Clean read-only 3-panel documentation
• Scalar: http://localhost:8000/scalar - Modern interactive documentation with beautiful design
• OpenAPI Schema: http://localhost:8000/openapi.json - Raw OpenAPI schema

⚠️ Authentication Required

All documentation pages are protected with HTTP Basic Authentication:

• Username: admin
• Password: secret123

Your browser will prompt for credentials when accessing /docs, /redoc, or /scalar.

Test the API

# Health check
curl http://localhost:8000/health

# Get all items
curl http://localhost:8000/items

# Create new item (requires Bearer token)
curl -X POST http://localhost:8000/items \
  -H "Authorization: Bearer demo-token-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Keyboard",
    "description": "Mechanical keyboard",
    "price": 150000,
    "is_available": true
  }'

Development Workflow

Using Makefile (Recommended)

make help       # Show all available commands
make install    # Install dependencies
make run        # Run development server
make test       # Run tests
make lint       # Check code quality
make format     # Format code
make typecheck  # Run type checker
make check      # Run all checks (lint + typecheck + test)
make clean      # Remove cache and build files

New to Make? See Makefile Guide for detailed instructions.

Manual Commands (Without Makefile)

Click to expand manual commands

Dependency Management

uv add package-name       # Add dependency
uv add --dev package-name # Add dev dependency
uv sync                   # Update dependencies
uv remove package-name    # Remove dependency

Testing

uv run pytest                        # Run tests
uv run pytest -v                     # Verbose output
uv run pytest --cov=src              # With coverage

Code Quality

uv run ruff check src/               # Lint check
uv run ruff check --fix src/         # Auto-fix issues
uv run ruff format src/              # Format code
uv run pyright src/                  # Type check

Project Structure

fastapi-docs-comparison/
├── src/
│   ├── __init__.py
│   └── main.py          # FastAPI application entry point
├── tests/
│   ├── __init__.py
│   └── test_main.py     # Test suite
├── Makefile             # Development commands
├── pyproject.toml       # Project configuration
├── README.md            # This file
└── MAKEFILE_GUIDE.md    # Makefile tutorial

API Endpoints

Root & Health

• GET / - API information
• GET /health - Health check

Items

• GET /items - List all items
• GET /items/{item_id} - Get specific item
• POST /items - Create new item (requires Bearer token)
• PUT /items/{item_id} - Update item (requires Bearer token)
• DELETE /items/{item_id} - Delete item (requires API key)

Users

• GET /users - List all users
• GET /users/{user_id} - Get specific user
• POST /users/profile - Create user profile with nested objects (requires API key)

Files

• POST /files/upload - Upload file with metadata (max 10MB)
• GET /files/download/sample - Download sample CSV file

Authentication

Bearer Token (for POST/PUT /items endpoints): Use the "Authorize" button in Swagger UI/Scalar or add Authorization: Bearer <token> header:

• demo-token-abc123 - Demo User
• test-token-xyz789 - Test User
• secure-token-2024 - Admin User

Example:

curl -X POST http://localhost:8000/items \
  -H "Authorization: Bearer demo-token-abc123" \
  -H "Content-Type: application/json" \
  -d '{"name":"Item","price":1000,"is_available":true}'

API Key (for other protected endpoints like /users/profile, DELETE /items): Add X-API-Key header with one of:

• demo-key-12345 - Demo User
• test-key-67890 - Test User

Documentation Tools Comparison

Swagger UI

• Type: Interactive documentation
• Key Features:
  • "Try it out" - Execute API calls directly from the browser
  • Request/response testing with real data
  • Authorization and authentication testing
  • Traditional, widely-used interface
• Best For: API testing, development, and debugging

Redoc

• Type: Read-only documentation
• Key Features:
  • Clean 3-panel layout (navigation, details, examples)
  • Search with Ctrl+K (Cmd+K on Mac)
  • Responsive design with dark mode
  • Download as standalone HTML
  • Excellent for public API documentation
• Best For: Public-facing documentation, API reference guides

Scalar

• Type: Interactive documentation
• Key Features:
  • Modern, beautiful design similar to Redoc
  • Interactive API testing like Swagger
  • Fast performance and smooth UX
  • Best of both worlds: design + functionality
• Best For: Modern applications wanting both aesthetics and interactivity

Implemented Features

Basic Documentation Setup

• Automatic OpenAPI spec generation
• Three documentation tools integration (Swagger UI, Redoc, Scalar)
• Endpoint grouping with tags
• Request/response schema documentation
• Example data provision

Advanced API Features

• Bearer token authentication (for POST/PUT /items endpoints)
• API key authentication (X-API-Key header)
• HTTP Basic Authentication for documentation pages
• Error response specifications with examples
• Complex parameter descriptions and constraints
• Nested object documentation
• File upload/download examples

Contributing

Contributions are welcome! To contribute:

1. Fork and clone the repository
2. Create a new branch: git checkout -b feature/your-feature
3. Make your changes and ensure all checks pass: make check
4. Commit and push your changes
5. Open a pull request

Code Standards

• Follow PEP 8 style guide
• Use type hints for all functions
• Write tests for new features
• Run make format before committing
• Ensure make check passes (lint + typecheck + test)

Documentation

• Makefile Guide - Understanding Make commands

References

• FastAPI Official Docs
• Swagger UI Official Docs
• Redoc Official Docs
• Scalar Official Docs
• uv Official Docs

License

This project is distributed under the MIT License. See LICENSE for details.