diff --git a/fastapi/applications.py b/fastapi/applications.py index 54175cb3b..8b66ddf72 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -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, diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py index 1a3abd80c..62b4674de 100644 --- a/fastapi/exceptions.py +++ b/fastapi/exceptions.py @@ -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, diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 82380f85d..632cc2c1d 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -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 `` 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", diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py index 0834fd741..9bd92be4c 100644 --- a/fastapi/param_functions.py +++ b/fastapi/param_functions.py @@ -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, diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py index fc49ba190..58ffc5c76 100644 --- a/fastapi/security/oauth2.py +++ b/fastapi/security/oauth2.py @@ -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,