Automatic API documentation (Swagger UI) in FastAPI - Performance & Optimization

Performance: Automatic API documentation (Swagger UI)

MEDIUM IMPACT

This affects the initial page load speed and rendering performance of the API docs interface.

Serving API documentation for developers

FastAPI

from fastapi import FastAPI
app = FastAPI(docs_url=None)  # disable default docs

# Serve Swagger UI only on demand or use lightweight alternative
# Or customize to lazy load Swagger UI assets

Reduces initial bundle size and delays loading heavy assets until user requests docs, improving load speed.

📈 Performance GainSaves ~200kb on initial load, reduces blocking time, improves LCP

Serving API documentation for developers

FastAPI

from fastapi import FastAPI
app = FastAPI(docs_url='/docs')  # default Swagger UI enabled

# No customization or lazy loading

Loads full Swagger UI assets on every docs page visit, increasing initial load time and blocking rendering.

📉 Performance CostAdds ~200kb of JS/CSS, blocks rendering for 100-200ms on slow connections

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Default Swagger UI enabled	Moderate (complex DOM for UI)	Multiple reflows during load	High paint cost due to heavy CSS/JS	[X] Bad
Swagger UI disabled or lazy loaded	Minimal DOM initially	Single reflow on demand	Lower paint cost, faster rendering	[OK] Good

Rendering Pipeline

Swagger UI assets (JS, CSS) are fetched and parsed during the Style Calculation and Paint stages. Large JS bundles block the main thread delaying Layout and Paint.

→Style Calculation

→Layout

→Paint

→Composite

⚠️ BottleneckPaint and Layout due to blocking JS and CSS parsing

Core Web Vital Affected

LCP

This affects the initial page load speed and rendering performance of the API docs interface.

Optimization Tips

1Avoid loading Swagger UI assets on every page if not needed.

2Use lazy loading or conditional loading for API docs UI.

3Monitor Largest Contentful Paint (LCP) when serving API documentation.

Performance Quiz - 3 Questions

How does enabling default Swagger UI in FastAPI affect page load performance?

A It has no impact on page load performance

B It reduces the bundle size and speeds up loading

C It adds extra JavaScript and CSS that can delay page rendering

D It improves browser caching automatically

DevTools: Performance

How to check: Open DevTools > Performance tab > Record page load of /docs > Look for long scripting and rendering tasks caused by Swagger UI scripts

What to look for: Long main thread blocking times and delayed Largest Contentful Paint (LCP) indicating heavy Swagger UI asset load

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