API Documentation with Swagger — Core Concepts

Swagger, OpenAPI, and Swagger UI — clearing up the names

The naming is confusing because of history. Swagger was the original name for both the spec format and the tools. In 2015, the spec was donated to the OpenAPI Initiative and renamed to OpenAPI Specification. The tools kept the Swagger name:

• OpenAPI Specification — the standard for describing APIs (the document format)
• Swagger UI — the interactive web interface for exploring an API
• Swagger Editor — a browser-based editor for writing OpenAPI specs
• Swagger Codegen — generates client/server code from specs (now mostly replaced by OpenAPI Generator)

When someone says “add Swagger to my API,” they usually mean “add Swagger UI so developers can interact with the documentation.”

Built-in docs in Python frameworks

FastAPI includes both Swagger UI and ReDoc by default:

• /docs — Swagger UI (interactive, “Try it out” buttons)
• /redoc — ReDoc (clean, read-only documentation)

No configuration needed. Both read from the auto-generated OpenAPI spec at /openapi.json.

Flask requires an extension. The most popular options:

• flask-smorest — generates OpenAPI specs from marshmallow schemas
• flask-restx — built-in Swagger UI with decorator-based docs (formerly flask-restplus)

Django REST Framework uses drf-spectacular or drf-yasg to generate specs and serve Swagger UI.

What makes documentation good

Having Swagger UI is the starting point, not the finish line. Good API docs need:

Clear descriptions on every endpoint. Not just “Get user” but “Retrieve a user by their unique ID. Returns 404 if the user doesn’t exist or has been deactivated.”

Documented error responses. Developers need to know not just what success looks like but what failure looks like. If your endpoint can return 400, 401, 403, 404, or 422, each should be documented with an example.

Request and response examples. Abstract schemas are harder to understand than concrete examples. {"name": "string", "age": "integer"} is less helpful than {"name": "Alice Chen", "age": 32}.

Meaningful parameter descriptions. user_id: int tells developers nothing they can’t see. user_id: int — The unique identifier returned when creating a user via POST /users tells them where to get the value.

Logical grouping. Group endpoints by resource (Users, Orders, Products) using tags. A flat list of 50 endpoints is hard to navigate.

Swagger UI vs ReDoc

Feature	Swagger UI	ReDoc
Interactive testing	Yes (“Try it out”)	No
Visual design	Functional	Cleaner, more readable
Three-panel layout	No	Yes (nav + content + examples)
Code samples	Limited	Built-in for multiple languages
Best for	Development, testing	Sharing with stakeholders

Many APIs offer both: Swagger UI for developers actively integrating, ReDoc for documentation that gets shared in emails and Slack.

Authentication in Swagger UI

Swagger UI supports “Authorize” buttons for testing protected endpoints:

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    swagger_ui_parameters={
        "persistAuthorization": True,  # Keep token across page refreshes
    },
)

For OAuth2 flows, Swagger UI can handle the full authorization code flow in the browser. For API key or bearer token auth, developers paste their token into the Authorize dialog and all subsequent requests include it.

Writing for your audience

API documentation serves different readers:

• Quickstart developers want a single curl command that works
• Integration developers need detailed parameter descriptions and error codes
• Architects want to understand the overall API design and authentication model

The OpenAPI spec handles the detailed reference docs. Supplement it with:

• A getting-started guide (outside the spec)
• Authentication setup instructions
• Rate limiting documentation
• Changelog for API versions

Common misconception

“Swagger UI IS the documentation.” Swagger UI is the interactive explorer — it’s great for testing but poor for learning. Developers new to your API need conceptual guides, tutorials, and examples that explain why, not just what. The best API docs combine Swagger UI (reference) with written guides (understanding).

One thing to remember: Swagger UI makes your API testable in a browser, but great documentation also needs descriptions, examples, and guides that help developers understand your API — not just call it.