happyz
/
fastapi
mirror of https://github.com/tiangolo/fastapi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

📝 Add links to related sections of docs to docstrings (#14776) 

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Motov Yurii 2026-02-04 15:41:54 +03:00 committed by GitHub
parent c9e512d808
commit 3a41403ccd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 190 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/docs/reference/request.md
View File

@ -2,6 +2,8 @@
You can declare a parameter in a *path operation function* or dependency to be of type `Request` and then you can access the raw request object directly, without any validation, etc.
Read more about it in the [FastAPI docs about using Request directly](https://fastapi.tiangolo.com/advanced/using-request-directly/)
You can import it directly from `fastapi`:
```python

2
docs/en/docs/reference/response.md
View File

@ -4,6 +4,8 @@ You can declare a parameter in a *path operation function* or dependency to be o
You can also use it directly to create an instance of it and return it from your *path operations*.
Read more about it in the [FastAPI docs about returning a custom Response](https://fastapi.tiangolo.com/advanced/response-directly/#returning-a-custom-response)
You can import it directly from `fastapi`:
```python

2
docs/en/docs/reference/responses.md
View File

@ -56,6 +56,8 @@ There are a couple of custom FastAPI response classes, you can use them to optim
## Starlette Responses
You can read more about all of them in the [FastAPI docs for Custom Response](https://fastapi.tiangolo.com/advanced/custom-response/) and in the [Starlette docs about Responses](https://starlette.dev/responses/).
::: fastapi.responses.FileResponse
options:
members:

2
docs/en/docs/reference/security/index.md
View File

@ -28,6 +28,8 @@ from fastapi.security import (
)
```
Read more about them in the [FastAPI docs about Security](https://fastapi.tiangolo.com/tutorial/security/).
## API Key Security Schemes
::: fastapi.security.APIKeyCookie

24
docs/en/docs/reference/websockets.md
View File

@ -2,6 +2,8 @@
When defining WebSockets, you normally declare a parameter of type `WebSocket` and with it you can read data from the client and send data to it.
Read more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
It is provided directly by Starlette, but you can import it from `fastapi`:
```python
@ -44,16 +46,6 @@ When you want to define dependencies that should be compatible with both HTTP an
- send_json
- close
When a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch it.
You can import it directly form `fastapi`:
```python
from fastapi import WebSocketDisconnect
```
::: fastapi.WebSocketDisconnect
## WebSockets - additional classes
Additional classes for handling WebSockets.
@ -66,4 +58,16 @@ from fastapi.websockets import WebSocketDisconnect, WebSocketState
::: fastapi.websockets.WebSocketDisconnect
When a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch it.
You can import it directly form `fastapi`:
```python
from fastapi import WebSocketDisconnect
```
Read more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/#handling-disconnections-and-multiple-clients)
::: fastapi.websockets.WebSocketState
`WebSocketState` is an enumeration of the possible states of a WebSocket connection.

7
fastapi/applications.py
View File

@ -672,7 +672,7 @@ class FastAPI(Starlette):
in the autogenerated OpenAPI using the `root_path`.
Read more about it in the
[FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root_path).
[FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root-path).
**Example**
@ -739,7 +739,7 @@ class FastAPI(Starlette):
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#deprecate-a-path-operation).
"""
),
] = None,
@ -812,6 +812,9 @@ class FastAPI(Starlette):
In this case, there would be two different schemas, one for input and
another one for output.
Read more about it in the
[FastAPI docs about how to separate schemas for input and output](https://fastapi.tiangolo.com/how-to/separate-openapi-schemas)
"""
),
] = True,

10
fastapi/exceptions.py
View File

@ -49,6 +49,9 @@ class HTTPException(StarletteHTTPException):
Doc(
"""
HTTP status code to send to the client.
Read more about it in the
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
"""
),
],
@ -58,6 +61,9 @@ class HTTPException(StarletteHTTPException):
"""
Any data to be sent to the client in the `detail` key of the JSON
response.
Read more about it in the
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
"""
),
] = None,
@ -66,6 +72,10 @@ class HTTPException(StarletteHTTPException):
Doc(
"""
Any headers to send to the client in the response.
Read more about it in the
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#add-custom-headers)
"""
),
] = None,

30
fastapi/openapi/docs.py
View File

@ -33,6 +33,9 @@ def get_swagger_ui_html(
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
Read more about it in the
[FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
"""
),
],
@ -41,6 +44,9 @@ def get_swagger_ui_html(
Doc(
"""
The HTML `<title>` content, normally shown in the browser tab.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
],
@ -51,6 +57,9 @@ def get_swagger_ui_html(
The URL to use to load the Swagger UI JavaScript.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
@ -61,6 +70,9 @@ def get_swagger_ui_html(
The URL to use to load the Swagger UI CSS.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
@ -77,6 +89,9 @@ def get_swagger_ui_html(
Doc(
"""
The OAuth2 redirect URL, it is normally automatically handled by FastAPI.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
] = None,
@ -85,6 +100,9 @@ def get_swagger_ui_html(
Doc(
"""
A dictionary with Swagger UI OAuth2 initialization configurations.
Read more about the available configuration options in the
[Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).
"""
),
] = None,
@ -95,6 +113,9 @@ def get_swagger_ui_html(
Configuration parameters for Swagger UI.
It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].
Read more about it in the
[FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).
"""
),
] = None,
@ -168,6 +189,9 @@ def get_redoc_html(
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
Read more about it in the
[FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
"""
),
],
@ -176,6 +200,9 @@ def get_redoc_html(
Doc(
"""
The HTML `<title>` content, normally shown in the browser tab.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
],
@ -186,6 +213,9 @@ def get_redoc_html(
The URL to use to load the ReDoc JavaScript.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js",

94
fastapi/param_functions.py
View File

@ -79,6 +79,9 @@ def Path( # noqa: N802
Doc(
"""
Human-readable title.
Read more about it in the
[FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#declare-metadata)
"""
),
] = None,
@ -96,6 +99,9 @@ def Path( # noqa: N802
"""
Greater than. If set, value must be greater than this. Only applicable to
numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -105,6 +111,9 @@ def Path( # noqa: N802
"""
Greater than or equal. If set, value must be greater than or equal to
this. Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -113,6 +122,9 @@ def Path( # noqa: N802
Doc(
"""
Less than. If set, value must be less than this. Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -122,6 +134,9 @@ def Path( # noqa: N802
"""
Less than or equal. If set, value must be less than or equal to this.
Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -213,6 +228,9 @@ def Path( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -343,6 +361,9 @@ def Query( # noqa: N802
Doc(
"""
Default value if the parameter field is not set.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alternative-old-query-as-the-default-value)
"""
),
] = Undefined,
@ -367,6 +388,9 @@ def Query( # noqa: N802
This will be used to extract the data and for the generated OpenAPI.
It is particularly useful when you can't use the name you want because it
is a Python reserved keyword or similar.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alias-parameters)
"""
),
] = None,
@ -402,6 +426,9 @@ def Query( # noqa: N802
Doc(
"""
Human-readable title.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
"""
),
] = None,
@ -410,6 +437,9 @@ def Query( # noqa: N802
Doc(
"""
Human-readable description.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
"""
),
] = None,
@ -419,6 +449,9 @@ def Query( # noqa: N802
"""
Greater than. If set, value must be greater than this. Only applicable to
numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -428,6 +461,9 @@ def Query( # noqa: N802
"""
Greater than or equal. If set, value must be greater than or equal to
this. Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -436,6 +472,9 @@ def Query( # noqa: N802
Doc(
"""
Less than. If set, value must be less than this. Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -445,6 +484,9 @@ def Query( # noqa: N802
"""
Less than or equal. If set, value must be less than or equal to this.
Only applicable to numbers.
Read more about it in the
[FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
"""
),
] = None,
@ -453,6 +495,9 @@ def Query( # noqa: N802
Doc(
"""
Minimum length for strings.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
"""
),
] = None,
@ -461,6 +506,9 @@ def Query( # noqa: N802
Doc(
"""
Maximum length for strings.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
"""
),
] = None,
@ -469,6 +517,9 @@ def Query( # noqa: N802
Doc(
"""
RegEx pattern for strings.
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#add-regular-expressions
"""
),
] = None,
@ -536,6 +587,9 @@ def Query( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -570,6 +624,9 @@ def Query( # noqa: N802
Mark this parameter field as deprecated.
It will affect the generated OpenAPI (e.g. visible at `/docs`).
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#deprecating-parameters)
"""
),
] = None,
@ -581,6 +638,9 @@ def Query( # noqa: N802
You probably don't need it, but it's available.
This affects the generated OpenAPI (e.g. visible at `/docs`).
Read more about it in the
[FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi
"""
),
] = True,
@ -849,6 +909,9 @@ def Header( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -1152,6 +1215,9 @@ def Cookie( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -1477,6 +1543,9 @@ def Body( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -1790,6 +1859,9 @@ def Form( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -2102,6 +2174,9 @@ def File( # noqa: N802
Doc(
"""
Example values for this field.
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
"""
),
] = None,
@ -2215,6 +2290,9 @@ def Depends( # noqa: N802
Don't call it directly, FastAPI will call it for you, just pass the object
directly.
Read more about it in the
[FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
"""
),
] = None,
@ -2230,6 +2308,9 @@ def Depends( # noqa: N802
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
Read more about it in the
[FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
"""
),
] = True,
@ -2250,6 +2331,9 @@ def Depends( # noqa: N802
that handles the request (similar to when using `"function"`), but end
**after** the response is sent back to the client. So, the dependency
function will be executed **around** the **request** and response cycle.
Read more about it in the
[FastAPI docs for FastAPI Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#early-exit-and-scope)
"""
),
] = None,
@ -2295,6 +2379,9 @@ def Security( # noqa: N802
Don't call it directly, FastAPI will call it for you, just pass the object
directly.
Read more about it in the
[FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
"""
),
] = None,
@ -2312,7 +2399,9 @@ def Security( # noqa: N802
These scopes are integrated with OpenAPI (and the API docs at `/docs`).
So they are visible in the OpenAPI specification.
)
Read more about it in the
[FastAPI docs about OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/)
"""
),
] = None,
@ -2327,6 +2416,9 @@ def Security( # noqa: N802
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
Read more about it in the
[FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
"""
),
] = True,

30
fastapi/security/oauth2.py
View File

@ -68,6 +68,9 @@ class OAuth2PasswordRequestForm:
"password". Nevertheless, this dependency class is permissive and
allows not passing it. If you want to enforce it, use instead the
`OAuth2PasswordRequestFormStrict` dependency.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
] = None,
@ -78,6 +81,9 @@ class OAuth2PasswordRequestForm:
"""
`username` string. The OAuth2 spec requires the exact field name
`username`.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -88,6 +94,9 @@ class OAuth2PasswordRequestForm:
"""
`password` string. The OAuth2 spec requires the exact field name
`password`.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -112,6 +121,9 @@ class OAuth2PasswordRequestForm:
* `users:read`
* `profile`
* `openid`
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
] = "",
@ -222,6 +234,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
"password". This dependency is strict about it. If you want to be
permissive, use instead the `OAuth2PasswordRequestForm` dependency
class.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -232,6 +247,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
"""
`username` string. The OAuth2 spec requires the exact field name
`username`.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -242,6 +260,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
"""
`password` string. The OAuth2 spec requires the exact field name
`password`.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -266,6 +287,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
* `users:read`
* `profile`
* `openid`
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
] = "",
@ -423,6 +447,9 @@ class OAuth2PasswordBearer(OAuth2):
"""
The URL to obtain the OAuth2 token. This would be the *path operation*
that has `OAuth2PasswordRequestForm` as a dependency.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
],
@ -442,6 +469,9 @@ class OAuth2PasswordBearer(OAuth2):
"""
The OAuth2 scopes that would be required by the *path operations* that
use this dependency.
Read more about it in the
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
),
] = None,