✏️ Report small docs improvements, including typos or broken links

[svlandeg]

Description

This thread should be used to report clear typos, broken links, or other small issues with the language used throughout the documentation.

Every once in a while, a maintainer will collect all these reports and will create a PR with all of them, to avoid having to review & merge many small PRs.

We will not be accepting any more user PRs to update typos, links or rephrasings of the documentation/tutorial.

[decorator-factory]

Not sure if this counts as a small improvement:

https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#add-regular-expressions
I think it's worth calling out that this does not use Python's re module for regular expressions, but rather Rust's regex crate through Pydantic (from https://pydantic.dev/docs/validation/latest/get-started/migration/#patterns--regex-on-strings). The syntax between the two regex engines differs. For example:

• $ in Python's re means "end of the string or before the \n at the end of the string", but in regex it just means the end
• In regex, \b{start} means start of a word, in re it means word boundary and then the string {start} literally
• No look-arounds and backreferences in regex

So if you try to reuse the pattern, you will have mismatches. E.g. doing re.search("^fixedquery$", q) is wrong

[YuriiMotov]

Invalid highlights in https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/
See PR #15854

[Yadidiah-k]

In docs/en/docs/advanced/behind-a-proxy.md, two Traefik URLs are outdated:

• Line 254: https://docs.traefik.io/ → https://doc.traefik.io/traefik/ (old docs domain, new one is canonical)
• Line 256: https://github.com/containous/traefik/releases → https://github.com/traefik/traefik/releases (org was renamed from containous to traefik)

[gitressa]

I am interested in FastAPI but haven't used it yet. So I visited https://fastapi.tiangolo.com/ and was impressed by the thorough documentation, and I look forward to diving in and trying it.

I block external fonts, so the typography looks a little strange, because there is a lot of space between the letters.

Proposal

Perhaps consider self hosting the fonts in the documentation since Zensical supports this?

Fonts

Zensical makes it easy to change the typeface of your project documentation, since it directly integrates with Google Fonts. Alternatively, fonts can be custom-loaded if self-hosting is preferred for data privacy reasons or if another destination should be used
[...]

From https://zensical.org/docs/setup/fonts/

It seems like these fonts are loaded, looking under Firefox > Network:

• https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,500,500i,700,700i|Roboto Mono:400,400i,700,700i&display=fallback
• https://fonts.googleapis.com/css2?family=Noto Color Emoji&display=swap

They are available via the Google Webfonts Helper tool:

• Roboto: https://gwfh.mranftl.com/fonts/roboto
• Roboto Mono: https://gwfh.mranftl.com/fonts/roboto-mono
• Noto Color Emoji: https://gwfh.mranftl.com/fonts/noto-color-emoji

[YuriiMotov]

Grammar and typos:

• ✏️ Fix grammar typo in HTTP Basic Auth docs: "a type of attacks" -> "… #15837
• Fix typos in docs and source code, fix status_code priority in _build_response_args #15699
• docs: fix grammar in handling-errors.md #15942
• docs: Fix phrasing 'To do it we use' -> 'To do this we use' in SQL da… #16036

Broken\dead links:

• fix(docs): replace dead Uber Ludwig blog link with project repo in 14 translations #15809
• docs(release-notes): fix dead pydantic v1 extra_types link #15822
• docs: fix 3 broken external links in en docs #15817
• 📝 Update renamed GitHub repo URLs for isort and ujson #15816
• 📝 Update ReDoc GitHub URLs from Rebilly/ReDoc to Redocly/redoc #15432
• The link to benchmarks in readme and documentation does not show the benchmarks #15798

Code line highlights:

• 📝 Fix out-of-range highlight lines in docs code embeds #15814
• 📝 Fix out-of-range highlight in advanced settings docs #15811

Invalid markdown:

• Fix invalid Markdown links in Query docstrings #16044

[cosmos-creator]

Cookie Parameters docs — misleading 422 error note

Location: docs/en/docs/tutorial/cookie-params.md and docs/en/docs/tutorial/cookie-param-models.md

Current text:

But even if you fill the data and click "Execute", because the docs UI works with JavaScript, the cookies won't be sent, and you will see an error message as if you didn't write any values.

Issue: This implies any missing cookie produces an error. That's only true for required cookie parameters (no default). For optional cookies, the request still succeeds and returns the default — that's expected behavior, not an error. Current wording is confusing and ambiguous as a fellow beginner like myself.

Suggested fix:

But even if you fill the data and click "Execute", because the docs UI works with JavaScript, the cookies won't be sent. If the cookie parameter is required (no default value), you will see an error message as if you didn't write any values. If the cookie parameter is optional (has a default value), the request will still work, you'll just get the default instead. This is expected, not a bug.

[cosing]

docs(zh): typo,fix markdown list spacing in oauth2 docs

Omitted spaces prevent the HTML from rendering correctly.

git apply << 'EOF'
diff --git a/docs/zh/docs/tutorial/security/index.md b/docs/zh/docs/tutorial/security/index.md
index a4c352110..4c992608c 100644
--- a/docs/zh/docs/tutorial/security/index.md
+++ b/docs/zh/docs/tutorial/security/index.md
@@ -79,7 +79,7 @@ OpenAPI 定义了以下安全方案：
     * HTTP Basic 认证方式。
     * HTTP Digest，等等。
 * `oauth2`：所有的 OAuth2 处理安全性的方式（称为「流程」）。
-    *以下几种流程适合构建 OAuth 2.0 身份认证的提供者（例如 Google，Facebook，X (Twitter)，GitHub 等）：
+    * 以下几种流程适合构建 OAuth 2.0 身份认证的提供者（例如 Google，Facebook，X (Twitter)，GitHub 等）：
         * `implicit`
         * `clientCredentials`
         * `authorizationCode`
EOF

[svlandeg]

#15968

[AdityaPrasad275]

Hi! First of all, thank you for the excellent documentation. I've been working through the FastAPI tutorial, and overall it's one of the best framework documentations I've read.

While reading the first OAuth2/security example here in the docs, I found it significantly harder to follow than the rest of the tutorial because it introduces multiple independent concepts at once.

For example, the example includes:

• User vs UserInDB model inheritance
• active vs inactive users (disabled)
• password hashing
• token decoding
• dependency chaining (get_current_user → get_current_active_user)

For someone trying to understand OAuth2 and dependencies for the first time, it's difficult to distinguish which pieces are essential for authentication and which are simply demonstrating additional patterns.

I think a simpler first example could focus on only:

• authenticating a user,
• generating an access token,
• retrieving the current user from that token.

Then later examples could progressively introduce password hashing, inactive users, response models, database models, etc.

While reading the example I also noticed one point of confusion:

get_current_user() returns UserInDB, while get_current_active_user() annotates its dependency as User. Although this is correct because UserInDB inherits from User, it initially made me wonder whether FastAPI was converting the object automatically or whether the type annotation was only expressing the minimum required interface.

Would the maintainers be open to simplifying the introductory example or adding a short explanation of these design choices? I'd be happy to help draft a simplified version if that would be useful.