📝 Fix docs issues reported in pinned discussion by YuriiMotov · Pull Request #16407 · fastapi/fastapi

YuriiMotov · 2026-09-28T18:40:14Z

This PR addresses docs issues reported in pinned discussion: #15849

It's probably easier to review this PR commit by commit - every commit is one fix.

codspeed · 2026-09-28T18:43:41Z

Merging this PR will not alter performance

✅ 24 untouched benchmarks

_{Comparing fix-docs-issues (7755ec3) with master (79d42b2)¹}

No successful run was found on master (c30032a) during the generation of this report, so 79d42b2 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

github-actions · 2026-09-28T18:44:00Z

📝 Docs preview

Last commit 7755ec3 at: https://a1e56705.fastapitiangolo.pages.dev

Modified Pages

…avior"

…ss is renamed"

…ed parameter

…curity/index.md`

…-validations.md"

YuriiMotov · 2026-09-28T19:03:54Z

 First, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md). Now using OAuth2 scopes:

-{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,67,109,111:114,118,125:128,133:139,144,160,175,180:182] *}


I checked it matches the real diff between tutorial004_an_py310.py and tutorial005_an_py310.py except adding one more item in fake_users_db, which is unrelated change

YuriiMotov · 2026-09-28T19:05:51Z


 In this case, it requires the scope `me` (it could require more than one scope).

+The `/status/` *path operation* uses `Depends(get_current_user)` without declaring any scopes. It requires a valid token, but no specific permissions.


This part of the diff wasn't explained, so I added a small note about it here and one more sentence below in Verify the scopes

YuriiMotov · 2026-09-28T19:07:18Z

 The `scopes` parameter receives a `dict` with each scope as a key and the description as the value:

-{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+{* ../../docs_src/security/tutorial005_an_py310.py ln[65:68] hl[67] *}


Also specified ln[...] in all code includes except the first one (in Global view) - to make it more readable

YuriiMotov · 2026-09-28T19:10:17Z

 Create a response as described in [Return a Response Directly](response-directly.md) and pass the headers as an additional parameter:

-{* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *}
+{* ../../docs_src/response_headers/tutorial001_py310.py hl[10:11] *}


Some highlights specified lines numbers that are out-of-range. See commit b2cea45

YuriiMotov · 2026-09-28T19:17:54Z

 Coming from the previous example, your `config.py` file could look like:

-{* ../../docs_src/settings/app02_an_py310/config.py hl[10] *}
+{* ../../docs_src/settings/app02_an_py310/config.py *}


No such line and no need to highlight anything. See preview

YuriiMotov · 2026-09-28T19:19:21Z

 In this example, it would link to a CSS file at `static/styles.css` with:

-```CSS hl_lines="4"
+```CSS


No such line and no need to highlight anything. See preview

YuriiMotov · 2026-09-28T19:20:12Z

 ///

-## Await for messages and send messages { #await-for-messages-and-send-messages }
+## Await messages and send messages { #await-messages-and-send-messages }


"await for something" is incorrect. It should be either "await something" or "wait for something"

YuriiMotov · 2026-09-28T19:23:43Z

 Create a utility function to generate a new access token.

-{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,82:90] *}
+{* ../../docs_src/security/tutorial004_an_py310.py ln[4:9,11:15,29:31,82:90] hl[4,7,13:15,29:31,82:90] *}


Hid the unrelated lines in code examples. Left the first code example unfolded.
Page preview: https://24b58251.fastapitiangolo.pages.dev/tutorial/security/simple-oauth2/

YuriiMotov · 2026-09-28T19:27:09Z

+/// note
+
+FastAPI uses Pydantic for data validation. In Pydantic v2, regular expressions use Rust's `regex` library by default. Its syntax and behavior have some differences from Python's `re` module.
+
+You can read more in the [Pydantic migration guide](https://pydantic.dev/docs/validation/latest/get-started/migration/#patterns--regex-on-strings).
+
+///
+


See motivation

YuriiMotov · 2026-09-28T19:29:23Z

+Then with `random.choice()` we can get a **random value** from the list, so, we get a tuple with `(id, item)`. It will be something like `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.

-Then we **assign those two values** of the tuple to the variables `id` and `name`.
+Then we **assign those two values** of the tuple to the variables `id` and `item`.


In code example the name of the variable is item:

fastapi/docs_src/query_params_str_validations/tutorial015_an_py310.py

Lines 22 to 30 in a3d205b

@app.get("/items/")

async def read_items(

id: Annotated[str | None, AfterValidator(check_valid_id)] = None,

):

if id:

item = data.get(id)

else:

id, item = random.choice(list(data.items()))

return {"id": id, "name": item}

YuriiMotov · 2026-09-28T19:30:53Z


 * Declaration of **parameters** from other different places such as: **headers**, **cookies**, **form fields** and **files**.
-* How to set **validation constraints** such as `maximum_length` or `regex`.
+* How to set **validation constraints** such as `max_length` or `pattern`.


maximum_length was probably a typo, and regex has been deprecated

YuriiMotov · 2026-09-28T19:33:48Z

-            detail="Incorrect username or password",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
+        raise HTTPException(status_code=400, detail="Incorrect username or password")


In tutorial 5 we already use status code 400 for this. And 400 is correct here.

fastapi/docs_src/security/tutorial005_an_py310.py

Lines 151 to 157 in a3d205b

@app.post("/token")

async def login_for_access_token(

form_data: Annotated[OAuth2PasswordRequestForm, Depends()],

) -> Token:

user = authenticate_user(fake_users_db, form_data.username, form_data.password)

if not user:

raise HTTPException(status_code=400, detail="Incorrect username or password")

YuriiMotov added 6 commits September 28, 2026 09:22

📝 Clarify regex behavior in query parameter validation docs

31751b8

📝 Update Traefik documentation link

3805719

📝 Fix invalid login response in JWT tutorial

5a5c1d4

📝 Fix code highlights in OAuth2 scopes docs

6417ff8

Hide unrelated lines in code examples in simple-oauth2.md

82a5a0c

Hide unrelated lines in code examples in oauth2-jwt.md

5438b78

YuriiMotov added the docs Documentation about how to use FastAPI label Sep 28, 2026

YuriiMotov added 13 commits September 28, 2026 20:58

Fix "request has an undefined behavior" -> "request has undefined beh…

2edbf53

…avior"

Fix broken markdown and double whitespace in docstrings

3b24f22

Fix "await for" -> "await"

3449a38

Add missing comma after an introductory clause

86b94b4

Fix "Starlette's exceptions is renamed" -> "Starlette's exception cla…

e21c5b3

…ss is renamed"

Fix outdated anchor

e7a32e4

Fix out-of-range line numbers in highlights

68c1d0e

Clarify cookie parameter validation error will only happen for requir…

3bbbac4

…ed parameter

Fix broken markdown (missing whitespace) in `docs/zh/docs/tutorial/se…

a2268d3

…curity/index.md`

Fix "re-use" -> "reuse"

509bcc1

Fix inconsistent variable names in text and code in "query-params-str…

b0ad586

…-validations.md"

Fix endpoint function name in extra_data_types code example

b727a33

Fix "maximum_length or regex" -> "max_length or pattern"

0c91857

YuriiMotov commented Sep 28, 2026

View reviewed changes

YuriiMotov marked this pull request as ready for review September 28, 2026 19:47

YuriiMotov force-pushed the fix-docs-issues branch from bb1aaa6 to 0c91857 Compare September 28, 2026 19:49

De-ASI-INTERFACE approved these changes Sep 29, 2026

View reviewed changes

Merge branch 'master' into fix-docs-issues

7755ec3


		In this case, it requires the scope `me` (it could require more than one scope).

		The `/status/` path operation uses `Depends(get_current_user)` without declaring any scopes. It requires a valid token, but no specific permissions.

	@app.get("/items/")
	async def read_items(
	id: Annotated[str \| None, AfterValidator(check_valid_id)] = None,
	):
	if id:
	item = data.get(id)
	else:
	id, item = random.choice(list(data.items()))
	return {"id": id, "name": item}

	@app.post("/token")
	async def login_for_access_token(
	form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
	) -> Token:
	user = authenticate_user(fake_users_db, form_data.username, form_data.password)
	if not user:
	raise HTTPException(status_code=400, detail="Incorrect username or password")

Uh oh!

Conversation

YuriiMotov commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Docs preview

Modified Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

YuriiMotov commented Sep 28, 2026 •

edited

Loading

codspeed Bot commented Sep 28, 2026 •

edited

Loading

github-actions Bot commented Sep 28, 2026 •

edited

Loading

YuriiMotov Sep 28, 2026 •

edited

Loading

YuriiMotov Sep 28, 2026 •

edited

Loading