Automatic API documentation (Swagger UI) in FastAPI - Mini Project: Build & Apply

Automatic API documentation (Swagger UI) with FastAPI

📖 Scenario: You are building a simple web API for a bookstore. You want to make it easy for other developers to see and test your API endpoints without writing extra documentation.

🎯 Goal: Create a FastAPI application that automatically generates interactive API documentation using Swagger UI.

📋 What You'll Learn

Create a FastAPI app instance named app

Define a GET endpoint at /books/ that returns a list of book titles

Use FastAPI's automatic documentation features to enable Swagger UI

Run the app so the documentation is accessible at /docs

💡 Why This Matters

🌍 Real World

APIs are used everywhere to let different programs talk to each other. Automatic documentation helps developers understand and test APIs quickly without extra writing.

💼 Career

Knowing how to build APIs with automatic docs is a key skill for backend developers, making your APIs easier to use and maintain.

1

Create the FastAPI app and initial data

Import FastAPI from fastapi and create an app instance called app. Then create a list called books with these exact strings: 'The Hobbit', '1984', 'Pride and Prejudice'.

FastAPI

from fastapi import FastAPI

# Create the FastAPI app instance
# Your code here

# Create the list of books
# Your code here

Hint

Use app = FastAPI() to create the app. Define books as a list with the exact book titles.

2

Add a GET endpoint to return the books list

Use the @app.get decorator with the path /books/ to create a function called read_books that returns the books list.

FastAPI

from fastapi import FastAPI

app = FastAPI()

books = ['The Hobbit', '1984', 'Pride and Prejudice']

# Add GET endpoint for /books/
# Your code here

Hint

Use @app.get('/books/') above the function. The function should return the books list.

3

Verify automatic Swagger UI documentation is enabled

Confirm that the FastAPI app app automatically provides Swagger UI documentation at /docs without extra code. No new code is needed here, just keep the existing code.

FastAPI

from fastapi import FastAPI

app = FastAPI()

books = ['The Hobbit', '1984', 'Pride and Prejudice']

@app.get('/books/')
def read_books():
    return books

# No new code needed here to enable Swagger UI
# Your code here

Hint

FastAPI enables Swagger UI automatically when you create app = FastAPI(). No extra code is needed.

4

Run the FastAPI app with Uvicorn

Add the code to run the app using uvicorn when the script is executed directly. Use if __name__ == '__main__': and call uvicorn.run with app, host '127.0.0.1', and port 8000.

FastAPI

from fastapi import FastAPI
import uvicorn

app = FastAPI()

books = ['The Hobbit', '1984', 'Pride and Prejudice']

@app.get('/books/')
def read_books():
    return books

# Add code to run the app with uvicorn
# Your code here

Hint

Import uvicorn. Use if __name__ == '__main__': to run uvicorn.run(app, host='127.0.0.1', port=8000).

Practice

1. What is the default URL path where FastAPI serves the automatic API documentation using Swagger UI?

easy

A. /docs

B. /swagger

C. /api-docs

D. /documentation

Solution

1. Step 1: Understand FastAPI default docs path

   FastAPI automatically provides Swagger UI documentation at the path '/docs' by default.

2. Step 2: Compare options with default path

   Among the options, only '/docs' matches the default URL for Swagger UI in FastAPI.

3. Final Answer:

   /docs -> Option A

4. Quick Check:

   Default Swagger UI docs path = /docs [OK]

Hint: Remember: FastAPI docs are at /docs by default [OK]

Common Mistakes:

• Confusing /swagger with /docs
• Assuming /api-docs is default
• Thinking documentation is at root /

2. Which of the following code snippets correctly imports and creates a FastAPI app that will have automatic Swagger UI documentation?

easy

A. import fastapi
app = fastapi.App()

B. from fastapi import API
app = API()

C. from fastapi import FastAPI
app = FastAPI()

D. import FastAPI
app = FastAPI()

Solution

1. Step 1: Check correct import and app creation

   The correct import is 'from fastapi import FastAPI' and app is created by calling FastAPI().

2. Step 2: Validate each option

   from fastapi import FastAPI app = FastAPI() matches the correct syntax. Options A, C, and D have wrong imports or class names.

3. Final Answer:

   from fastapi import FastAPI\napp = FastAPI() -> Option C

4. Quick Check:

   Correct import and app creation = from fastapi import FastAPI app = FastAPI() [OK]

Hint: FastAPI app is created by FastAPI() after correct import [OK]

Common Mistakes:

• Using wrong import names like API or App
• Trying to import FastAPI with capital letter as module
• Calling wrong constructor names

3. Given this FastAPI code snippet, what will you see when you open http://localhost:8000/docs in your browser?

from fastapi import FastAPI
app = FastAPI()

@app.get("/hello")
def say_hello():
    return {"message": "Hello, world!"}

medium

A. A 404 Not Found error because /docs is not defined

B. A plain JSON response with {"message": "Hello, world!"}

C. A blank page with no content

D. An interactive Swagger UI showing the /hello GET endpoint with a Try it out button

Solution

1. Step 1: Understand FastAPI automatic docs behavior

   FastAPI automatically generates Swagger UI at /docs showing all defined endpoints.

2. Step 2: Analyze the given code

   The code defines a GET endpoint /hello. The docs page will list this endpoint with interactive testing.

3. Final Answer:

   An interactive Swagger UI showing the /hello GET endpoint with a Try it out button -> Option D

4. Quick Check:

   FastAPI auto docs show endpoints interactively at /docs [OK]

Hint: Open /docs to see interactive API docs with all endpoints [OK]

Common Mistakes:

• Expecting JSON response at /docs instead of UI
• Thinking /docs must be manually coded
• Confusing /docs with endpoint paths

4. You wrote this FastAPI app but when you visit /docs, you get a 404 error. What is the likely cause?

from fastapi import FastAPI
app = FastAPI()

@app.get("/items")
def read_items():
    return [{"item_id": 1}]

# You run the app with: uvicorn main:app --port 8000 --host 0.0.0.0

# But /docs returns 404

medium

A. You are running the app with the wrong module or app name

B. The endpoint /items is missing

C. You need to add extra code to enable /docs

D. You forgot to import FastAPI

Solution

1. Step 1: Check the run command and app reference

   The command 'uvicorn main:app' requires a file named main.py with an app variable.

2. Step 2: Identify mismatch causing 404 on /docs

   If the file or app name is wrong, uvicorn won't serve the correct app, so /docs is missing.

3. Final Answer:

   You are running the app with the wrong module or app name -> Option A

4. Quick Check:

   Run command must match file and app names exactly [OK]

Hint: Match uvicorn run command module:app exactly [OK]

Common Mistakes:

• Assuming /docs needs manual enabling
• Forgetting to import FastAPI (but code shows import)
• Thinking missing endpoint causes /docs 404

5. You want to customize the automatic API docs path from the default /docs to /api-docs. Which FastAPI app creation code achieves this?

hard

A. app = FastAPI(swagger_ui_url="/api-docs")

B. app = FastAPI(docs_url="/api-docs")

C. app = FastAPI(openapi_url="/api-docs")

D. app = FastAPI(docs_path="/api-docs")

Solution

1. Step 1: Identify FastAPI parameter for docs path

   The parameter to change Swagger UI docs path is docs_url.

2. Step 2: Match option with correct parameter

   app = FastAPI(docs_url="/api-docs") uses docs_url="/api-docs", which correctly changes the docs path.

3. Final Answer:

   app = FastAPI(docs_url="/api-docs") -> Option B

4. Quick Check:

   Change docs path with docs_url parameter [OK]

Hint: Use docs_url to set custom docs path [OK]

Common Mistakes:

• Using swagger_ui_url which changes UI assets path
• Changing openapi_url affects JSON schema, not docs UI
• Using docs_path which is not a valid parameter