4586 lines
172 KiB
Python
4586 lines
172 KiB
Python
from enum import Enum
|
|
from typing import (
|
|
Any,
|
|
Awaitable,
|
|
Callable,
|
|
Coroutine,
|
|
Dict,
|
|
List,
|
|
Optional,
|
|
Sequence,
|
|
Type,
|
|
TypeVar,
|
|
Union,
|
|
)
|
|
|
|
from fastapi import routing
|
|
from fastapi.datastructures import Default, DefaultPlaceholder
|
|
from fastapi.exception_handlers import (
|
|
http_exception_handler,
|
|
request_validation_exception_handler,
|
|
websocket_request_validation_exception_handler,
|
|
)
|
|
from fastapi.exceptions import RequestValidationError, WebSocketRequestValidationError
|
|
from fastapi.logger import logger
|
|
from fastapi.openapi.docs import (
|
|
get_redoc_html,
|
|
get_swagger_ui_html,
|
|
get_swagger_ui_oauth2_redirect_html,
|
|
)
|
|
from fastapi.openapi.utils import get_openapi
|
|
from fastapi.params import Depends
|
|
from fastapi.types import DecoratedCallable, IncEx
|
|
from fastapi.utils import generate_unique_id
|
|
from starlette.applications import Starlette
|
|
from starlette.datastructures import State
|
|
from starlette.exceptions import HTTPException
|
|
from starlette.middleware import Middleware
|
|
from starlette.middleware.base import BaseHTTPMiddleware
|
|
from starlette.requests import Request
|
|
from starlette.responses import HTMLResponse, JSONResponse, Response
|
|
from starlette.routing import BaseRoute
|
|
from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send
|
|
from typing_extensions import Annotated, Doc, deprecated
|
|
|
|
AppType = TypeVar("AppType", bound="FastAPI")
|
|
|
|
|
|
class FastAPI(Starlette):
|
|
"""
|
|
`FastAPI` app class, the main entrypoint to use FastAPI.
|
|
|
|
Read more in the
|
|
[FastAPI docs for First Steps](https://fastapi.tiangolo.com/tutorial/first-steps/).
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
```
|
|
"""
|
|
|
|
def __init__(
|
|
self: AppType,
|
|
*,
|
|
debug: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Boolean indicating if debug tracebacks should be returned on server
|
|
errors.
|
|
|
|
Read more in the
|
|
[Starlette docs for Applications](https://www.starlette.io/applications/#instantiating-the-application).
|
|
"""
|
|
),
|
|
] = False,
|
|
routes: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
**Note**: you probably shouldn't use this parameter, it is inherited
|
|
from Starlette and supported for compatibility.
|
|
|
|
---
|
|
|
|
A list of routes to serve incoming HTTP and WebSocket requests.
|
|
"""
|
|
),
|
|
deprecated(
|
|
"""
|
|
You normally wouldn't use this parameter with FastAPI, it is inherited
|
|
from Starlette and supported for compatibility.
|
|
|
|
In FastAPI, you normally would use the *path operation methods*,
|
|
like `app.get()`, `app.post()`, etc.
|
|
"""
|
|
),
|
|
] = None,
|
|
title: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The title of the API.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(title="ChimichangApp")
|
|
```
|
|
"""
|
|
),
|
|
] = "FastAPI",
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A short summary of the API.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(summary="Deadpond's favorite app. Nuff said.")
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
str,
|
|
Doc(
|
|
'''
|
|
A description of the API. Supports Markdown (using
|
|
[CommonMark syntax](https://commonmark.org/)).
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(
|
|
description="""
|
|
ChimichangApp API helps you do awesome stuff. 🚀
|
|
|
|
## Items
|
|
|
|
You can **read items**.
|
|
|
|
## Users
|
|
|
|
You will be able to:
|
|
|
|
* **Create users** (_not implemented_).
|
|
* **Read users** (_not implemented_).
|
|
|
|
"""
|
|
)
|
|
```
|
|
'''
|
|
),
|
|
] = "",
|
|
version: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The version of the API.
|
|
|
|
**Note** This is the version of your application, not the version of
|
|
the OpenAPI specification nor the version of FastAPI being used.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(version="0.0.1")
|
|
```
|
|
"""
|
|
),
|
|
] = "0.1.0",
|
|
openapi_url: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
The URL where the OpenAPI schema will be served from.
|
|
|
|
If you set it to `None`, no OpenAPI schema will be served publicly, and
|
|
the default automatic endpoints `/docs` and `/redoc` will also be
|
|
disabled.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#openapi-url).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(openapi_url="/api/v1/openapi.json")
|
|
```
|
|
"""
|
|
),
|
|
] = "/openapi.json",
|
|
openapi_tags: Annotated[
|
|
Optional[List[Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
A list of tags used by OpenAPI, these are the same `tags` you can set
|
|
in the *path operations*, like:
|
|
|
|
* `@app.get("/users/", tags=["users"])`
|
|
* `@app.get("/items/", tags=["items"])`
|
|
|
|
The order of the tags can be used to specify the order shown in
|
|
tools like Swagger UI, used in the automatic path `/docs`.
|
|
|
|
It's not required to specify all the tags used.
|
|
|
|
The tags that are not declared MAY be organized randomly or based
|
|
on the tools' logic. Each tag name in the list MUST be unique.
|
|
|
|
The value of each item is a `dict` containing:
|
|
|
|
* `name`: The name of the tag.
|
|
* `description`: A short description of the tag.
|
|
[CommonMark syntax](https://commonmark.org/) MAY be used for rich
|
|
text representation.
|
|
* `externalDocs`: Additional external documentation for this tag. If
|
|
provided, it would contain a `dict` with:
|
|
* `description`: A short description of the target documentation.
|
|
[CommonMark syntax](https://commonmark.org/) MAY be used for
|
|
rich text representation.
|
|
* `url`: The URL for the target documentation. Value MUST be in
|
|
the form of a URL.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
tags_metadata = [
|
|
{
|
|
"name": "users",
|
|
"description": "Operations with users. The **login** logic is also here.",
|
|
},
|
|
{
|
|
"name": "items",
|
|
"description": "Manage items. So _fancy_ they have their own docs.",
|
|
"externalDocs": {
|
|
"description": "Items external docs",
|
|
"url": "https://fastapi.tiangolo.com/",
|
|
},
|
|
},
|
|
]
|
|
|
|
app = FastAPI(openapi_tags=tags_metadata)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
servers: Annotated[
|
|
Optional[List[Dict[str, Union[str, Any]]]],
|
|
Doc(
|
|
"""
|
|
A `list` of `dict`s with connectivity information to a target server.
|
|
|
|
You would use it, for example, if your application is served from
|
|
different domains and you want to use the same Swagger UI in the
|
|
browser to interact with each of them (instead of having multiple
|
|
browser tabs open). Or if you want to leave fixed the possible URLs.
|
|
|
|
If the servers `list` is not provided, or is an empty `list`, the
|
|
default value would be a `dict` with a `url` value of `/`.
|
|
|
|
Each item in the `list` is a `dict` containing:
|
|
|
|
* `url`: A URL to the target host. This URL supports Server Variables
|
|
and MAY be relative, to indicate that the host location is relative
|
|
to the location where the OpenAPI document is being served. Variable
|
|
substitutions will be made when a variable is named in `{`brackets`}`.
|
|
* `description`: An optional string describing the host designated by
|
|
the URL. [CommonMark syntax](https://commonmark.org/) MAY be used for
|
|
rich text representation.
|
|
* `variables`: A `dict` between a variable name and its value. The value
|
|
is used for substitution in the server's URL template.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#additional-servers).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(
|
|
servers=[
|
|
{"url": "https://stag.example.com", "description": "Staging environment"},
|
|
{"url": "https://prod.example.com", "description": "Production environment"},
|
|
]
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of global dependencies, they will be applied to each
|
|
*path operation*, including in sub-routers.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Global Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/global-dependencies/).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import Depends, FastAPI
|
|
|
|
from .dependencies import func_dep_1, func_dep_2
|
|
|
|
app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)])
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
default_response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
The default response class to be used.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from fastapi.responses import ORJSONResponse
|
|
|
|
app = FastAPI(default_response_class=ORJSONResponse)
|
|
```
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
redirect_slashes: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Whether to detect and redirect slashes in URLs when the client doesn't
|
|
use the same format.
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(redirect_slashes=True) # the default
|
|
|
|
@app.get("/items/")
|
|
async def read_items():
|
|
return [{"item_id": "Foo"}]
|
|
```
|
|
|
|
With this app, if a client goes to `/items` (without a trailing slash),
|
|
they will be automatically redirected with an HTTP status code of 307
|
|
to `/items/`.
|
|
"""
|
|
),
|
|
] = True,
|
|
docs_url: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
The path to the automatic interactive API documentation.
|
|
It is handled in the browser by Swagger UI.
|
|
|
|
The default URL is `/docs`. You can disable it by setting it to `None`.
|
|
|
|
If `openapi_url` is set to `None`, this will be automatically disabled.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(docs_url="/documentation", redoc_url=None)
|
|
```
|
|
"""
|
|
),
|
|
] = "/docs",
|
|
redoc_url: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
The path to the alternative automatic interactive API documentation
|
|
provided by ReDoc.
|
|
|
|
The default URL is `/redoc`. You can disable it by setting it to `None`.
|
|
|
|
If `openapi_url` is set to `None`, this will be automatically disabled.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(docs_url="/documentation", redoc_url="redocumentation")
|
|
```
|
|
"""
|
|
),
|
|
] = "/redoc",
|
|
swagger_ui_oauth2_redirect_url: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
The OAuth2 redirect endpoint for the Swagger UI.
|
|
|
|
By default it is `/docs/oauth2-redirect`.
|
|
|
|
This is only used if you use OAuth2 (with the "Authorize" button)
|
|
with Swagger UI.
|
|
"""
|
|
),
|
|
] = "/docs/oauth2-redirect",
|
|
swagger_ui_init_oauth: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
OAuth2 configuration for the Swagger UI, by default shown at `/docs`.
|
|
|
|
Read more about the available configuration options in the
|
|
[Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).
|
|
"""
|
|
),
|
|
] = None,
|
|
middleware: Annotated[
|
|
Optional[Sequence[Middleware]],
|
|
Doc(
|
|
"""
|
|
List of middleware to be added when creating the application.
|
|
|
|
In FastAPI you would normally do this with `app.add_middleware()`
|
|
instead.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/).
|
|
"""
|
|
),
|
|
] = None,
|
|
exception_handlers: Annotated[
|
|
Optional[
|
|
Dict[
|
|
Union[int, Type[Exception]],
|
|
Callable[[Request, Any], Coroutine[Any, Any, Response]],
|
|
]
|
|
],
|
|
Doc(
|
|
"""
|
|
A dictionary with handlers for exceptions.
|
|
|
|
In FastAPI, you would normally use the decorator
|
|
`@app.exception_handler()`.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).
|
|
"""
|
|
),
|
|
] = None,
|
|
on_startup: Annotated[
|
|
Optional[Sequence[Callable[[], Any]]],
|
|
Doc(
|
|
"""
|
|
A list of startup event handler functions.
|
|
|
|
You should instead use the `lifespan` handlers.
|
|
|
|
Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
|
|
"""
|
|
),
|
|
] = None,
|
|
on_shutdown: Annotated[
|
|
Optional[Sequence[Callable[[], Any]]],
|
|
Doc(
|
|
"""
|
|
A list of shutdown event handler functions.
|
|
|
|
You should instead use the `lifespan` handlers.
|
|
|
|
Read more in the
|
|
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
|
|
"""
|
|
),
|
|
] = None,
|
|
lifespan: Annotated[
|
|
Optional[Lifespan[AppType]],
|
|
Doc(
|
|
"""
|
|
A `Lifespan` context manager handler. This replaces `startup` and
|
|
`shutdown` functions with a single context manager.
|
|
|
|
Read more in the
|
|
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
|
|
"""
|
|
),
|
|
] = None,
|
|
terms_of_service: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A URL to the Terms of Service for your API.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more at the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
app = FastAPI(terms_of_service="http://example.com/terms/")
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
contact: Annotated[
|
|
Optional[Dict[str, Union[str, Any]]],
|
|
Doc(
|
|
"""
|
|
A dictionary with the contact information for the exposed API.
|
|
|
|
It can contain several fields.
|
|
|
|
* `name`: (`str`) The name of the contact person/organization.
|
|
* `url`: (`str`) A URL pointing to the contact information. MUST be in
|
|
the format of a URL.
|
|
* `email`: (`str`) The email address of the contact person/organization.
|
|
MUST be in the format of an email address.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more at the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
app = FastAPI(
|
|
contact={
|
|
"name": "Deadpoolio the Amazing",
|
|
"url": "http://x-force.example.com/contact/",
|
|
"email": "dp@x-force.example.com",
|
|
}
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
license_info: Annotated[
|
|
Optional[Dict[str, Union[str, Any]]],
|
|
Doc(
|
|
"""
|
|
A dictionary with the license information for the exposed API.
|
|
|
|
It can contain several fields.
|
|
|
|
* `name`: (`str`) **REQUIRED** (if a `license_info` is set). The
|
|
license name used for the API.
|
|
* `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression
|
|
for the API. The `identifier` field is mutually exclusive of the `url`
|
|
field. Available since OpenAPI 3.1.0, FastAPI 0.99.0.
|
|
* `url`: (`str`) A URL to the license used for the API. This MUST be
|
|
the format of a URL.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more at the
|
|
[FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
app = FastAPI(
|
|
license_info={
|
|
"name": "Apache 2.0",
|
|
"url": "https://www.apache.org/licenses/LICENSE-2.0.html",
|
|
}
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_prefix: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
A URL prefix for the OpenAPI URL.
|
|
"""
|
|
),
|
|
deprecated(
|
|
"""
|
|
"openapi_prefix" has been deprecated in favor of "root_path", which
|
|
follows more closely the ASGI standard, is simpler, and more
|
|
automatic.
|
|
"""
|
|
),
|
|
] = "",
|
|
root_path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
A path prefix handled by a proxy that is not seen by the application
|
|
but is seen by external clients, which affects things like Swagger UI.
|
|
|
|
Read more about it at the
|
|
[FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(root_path="/api/v1")
|
|
```
|
|
"""
|
|
),
|
|
] = "",
|
|
root_path_in_servers: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
To disable automatically generating the URLs in the `servers` field
|
|
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).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI(root_path_in_servers=False)
|
|
```
|
|
"""
|
|
),
|
|
] = True,
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses to be shown in OpenAPI.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).
|
|
|
|
And in the
|
|
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
OpenAPI callbacks that should apply to all *path operations*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
webhooks: Annotated[
|
|
Optional[routing.APIRouter],
|
|
Doc(
|
|
"""
|
|
Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't
|
|
depend on specific *path operations*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
**Note**: This is available since OpenAPI 3.1.0, FastAPI 0.99.0.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark all *path operations* as deprecated. You probably don't need it,
|
|
but it's available.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
To include (or not) all the *path operations* in the generated OpenAPI.
|
|
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 for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
swagger_ui_parameters: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Parameters to configure Swagger UI, the autogenerated interactive API
|
|
documentation (by default at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
separate_input_output_schemas: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Whether to generate separate OpenAPI schemas for request body and
|
|
response body when the results would be more precise.
|
|
|
|
This is particularly useful when automatically generating clients.
|
|
|
|
For example, if you have a model like:
|
|
|
|
```python
|
|
from pydantic import BaseModel
|
|
|
|
class Item(BaseModel):
|
|
name: str
|
|
tags: list[str] = []
|
|
```
|
|
|
|
When `Item` is used for input, a request body, `tags` is not required,
|
|
the client doesn't have to provide it.
|
|
|
|
But when using `Item` for output, for a response body, `tags` is always
|
|
available because it has a default value, even if it's just an empty
|
|
list. So, the client should be able to always expect it.
|
|
|
|
In this case, there would be two different schemas, one for input and
|
|
another one for output.
|
|
"""
|
|
),
|
|
] = True,
|
|
**extra: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
Extra keyword arguments to be stored in the app, not used by FastAPI
|
|
anywhere.
|
|
"""
|
|
),
|
|
],
|
|
) -> None:
|
|
self.debug = debug
|
|
self.title = title
|
|
self.summary = summary
|
|
self.description = description
|
|
self.version = version
|
|
self.terms_of_service = terms_of_service
|
|
self.contact = contact
|
|
self.license_info = license_info
|
|
self.openapi_url = openapi_url
|
|
self.openapi_tags = openapi_tags
|
|
self.root_path_in_servers = root_path_in_servers
|
|
self.docs_url = docs_url
|
|
self.redoc_url = redoc_url
|
|
self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url
|
|
self.swagger_ui_init_oauth = swagger_ui_init_oauth
|
|
self.swagger_ui_parameters = swagger_ui_parameters
|
|
self.servers = servers or []
|
|
self.separate_input_output_schemas = separate_input_output_schemas
|
|
self.extra = extra
|
|
self.openapi_version: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The version string of OpenAPI.
|
|
|
|
FastAPI will generate OpenAPI version 3.1.0, and will output that as
|
|
the OpenAPI version. But some tools, even though they might be
|
|
compatible with OpenAPI 3.1.0, might not recognize it as a valid.
|
|
|
|
So you could override this value to trick those tools into using
|
|
the generated OpenAPI. Have in mind that this is a hack. But if you
|
|
avoid using features added in OpenAPI 3.1.0, it might work for your
|
|
use case.
|
|
|
|
This is not passed as a parameter to the `FastAPI` class to avoid
|
|
giving the false idea that FastAPI would generate a different OpenAPI
|
|
schema. It is only available as an attribute.
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
app.openapi_version = "3.0.2"
|
|
```
|
|
"""
|
|
),
|
|
] = "3.1.0"
|
|
self.openapi_schema: Optional[Dict[str, Any]] = None
|
|
if self.openapi_url:
|
|
assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'"
|
|
assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'"
|
|
# TODO: remove when discarding the openapi_prefix parameter
|
|
if openapi_prefix:
|
|
logger.warning(
|
|
'"openapi_prefix" has been deprecated in favor of "root_path", which '
|
|
"follows more closely the ASGI standard, is simpler, and more "
|
|
"automatic. Check the docs at "
|
|
"https://fastapi.tiangolo.com/advanced/sub-applications/"
|
|
)
|
|
self.webhooks: Annotated[
|
|
routing.APIRouter,
|
|
Doc(
|
|
"""
|
|
The `app.webhooks` attribute is an `APIRouter` with the *path
|
|
operations* that will be used just for documentation of webhooks.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/).
|
|
"""
|
|
),
|
|
] = webhooks or routing.APIRouter()
|
|
self.root_path = root_path or openapi_prefix
|
|
self.state: Annotated[
|
|
State,
|
|
Doc(
|
|
"""
|
|
A state object for the application. This is the same object for the
|
|
entire application, it doesn't change from request to request.
|
|
|
|
You normally wouldn't use this in FastAPI, for most of the cases you
|
|
would instead use FastAPI dependencies.
|
|
|
|
This is simply inherited from Starlette.
|
|
|
|
Read more about it in the
|
|
[Starlette docs for Applications](https://www.starlette.io/applications/#storing-state-on-the-app-instance).
|
|
"""
|
|
),
|
|
] = State()
|
|
self.dependency_overrides: Annotated[
|
|
Dict[Callable[..., Any], Callable[..., Any]],
|
|
Doc(
|
|
"""
|
|
A dictionary with overrides for the dependencies.
|
|
|
|
Each key is the original dependency callable, and the value is the
|
|
actual dependency that should be called.
|
|
|
|
This is for testing, to replace expensive dependencies with testing
|
|
versions.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Testing Dependencies with Overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/).
|
|
"""
|
|
),
|
|
] = {}
|
|
self.router: routing.APIRouter = routing.APIRouter(
|
|
routes=routes,
|
|
redirect_slashes=redirect_slashes,
|
|
dependency_overrides_provider=self,
|
|
on_startup=on_startup,
|
|
on_shutdown=on_shutdown,
|
|
lifespan=lifespan,
|
|
default_response_class=default_response_class,
|
|
dependencies=dependencies,
|
|
callbacks=callbacks,
|
|
deprecated=deprecated,
|
|
include_in_schema=include_in_schema,
|
|
responses=responses,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
self.exception_handlers: Dict[
|
|
Any, Callable[[Request, Any], Union[Response, Awaitable[Response]]]
|
|
] = {} if exception_handlers is None else dict(exception_handlers)
|
|
self.exception_handlers.setdefault(HTTPException, http_exception_handler)
|
|
self.exception_handlers.setdefault(
|
|
RequestValidationError, request_validation_exception_handler
|
|
)
|
|
self.exception_handlers.setdefault(
|
|
WebSocketRequestValidationError,
|
|
# Starlette still has incorrect type specification for the handlers
|
|
websocket_request_validation_exception_handler, # type: ignore
|
|
)
|
|
|
|
self.user_middleware: List[Middleware] = (
|
|
[] if middleware is None else list(middleware)
|
|
)
|
|
self.middleware_stack: Union[ASGIApp, None] = None
|
|
self.setup()
|
|
|
|
def openapi(self) -> Dict[str, Any]:
|
|
"""
|
|
Generate the OpenAPI schema of the application. This is called by FastAPI
|
|
internally.
|
|
|
|
The first time it is called it stores the result in the attribute
|
|
`app.openapi_schema`, and next times it is called, it just returns that same
|
|
result. To avoid the cost of generating the schema every time.
|
|
|
|
If you need to modify the generated OpenAPI schema, you could modify it.
|
|
|
|
Read more in the
|
|
[FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/).
|
|
"""
|
|
if not self.openapi_schema:
|
|
self.openapi_schema = get_openapi(
|
|
title=self.title,
|
|
version=self.version,
|
|
openapi_version=self.openapi_version,
|
|
summary=self.summary,
|
|
description=self.description,
|
|
terms_of_service=self.terms_of_service,
|
|
contact=self.contact,
|
|
license_info=self.license_info,
|
|
routes=self.routes,
|
|
webhooks=self.webhooks.routes,
|
|
tags=self.openapi_tags,
|
|
servers=self.servers,
|
|
separate_input_output_schemas=self.separate_input_output_schemas,
|
|
)
|
|
return self.openapi_schema
|
|
|
|
def setup(self) -> None:
|
|
if self.openapi_url:
|
|
urls = (server_data.get("url") for server_data in self.servers)
|
|
server_urls = {url for url in urls if url}
|
|
|
|
async def openapi(req: Request) -> JSONResponse:
|
|
root_path = req.scope.get("root_path", "").rstrip("/")
|
|
if root_path not in server_urls:
|
|
if root_path and self.root_path_in_servers:
|
|
self.servers.insert(0, {"url": root_path})
|
|
server_urls.add(root_path)
|
|
return JSONResponse(self.openapi())
|
|
|
|
self.add_route(self.openapi_url, openapi, include_in_schema=False)
|
|
if self.openapi_url and self.docs_url:
|
|
|
|
async def swagger_ui_html(req: Request) -> HTMLResponse:
|
|
root_path = req.scope.get("root_path", "").rstrip("/")
|
|
openapi_url = root_path + self.openapi_url
|
|
oauth2_redirect_url = self.swagger_ui_oauth2_redirect_url
|
|
if oauth2_redirect_url:
|
|
oauth2_redirect_url = root_path + oauth2_redirect_url
|
|
return get_swagger_ui_html(
|
|
openapi_url=openapi_url,
|
|
title=f"{self.title} - Swagger UI",
|
|
oauth2_redirect_url=oauth2_redirect_url,
|
|
init_oauth=self.swagger_ui_init_oauth,
|
|
swagger_ui_parameters=self.swagger_ui_parameters,
|
|
)
|
|
|
|
self.add_route(self.docs_url, swagger_ui_html, include_in_schema=False)
|
|
|
|
if self.swagger_ui_oauth2_redirect_url:
|
|
|
|
async def swagger_ui_redirect(req: Request) -> HTMLResponse:
|
|
return get_swagger_ui_oauth2_redirect_html()
|
|
|
|
self.add_route(
|
|
self.swagger_ui_oauth2_redirect_url,
|
|
swagger_ui_redirect,
|
|
include_in_schema=False,
|
|
)
|
|
if self.openapi_url and self.redoc_url:
|
|
|
|
async def redoc_html(req: Request) -> HTMLResponse:
|
|
root_path = req.scope.get("root_path", "").rstrip("/")
|
|
openapi_url = root_path + self.openapi_url
|
|
return get_redoc_html(
|
|
openapi_url=openapi_url, title=f"{self.title} - ReDoc"
|
|
)
|
|
|
|
self.add_route(self.redoc_url, redoc_html, include_in_schema=False)
|
|
|
|
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
|
|
if self.root_path:
|
|
scope["root_path"] = self.root_path
|
|
await super().__call__(scope, receive, send)
|
|
|
|
def add_api_route(
|
|
self,
|
|
path: str,
|
|
endpoint: Callable[..., Coroutine[Any, Any, Response]],
|
|
*,
|
|
response_model: Any = Default(None),
|
|
status_code: Optional[int] = None,
|
|
tags: Optional[List[Union[str, Enum]]] = None,
|
|
dependencies: Optional[Sequence[Depends]] = None,
|
|
summary: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
response_description: str = "Successful Response",
|
|
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
|
|
deprecated: Optional[bool] = None,
|
|
methods: Optional[List[str]] = None,
|
|
operation_id: Optional[str] = None,
|
|
response_model_include: Optional[IncEx] = None,
|
|
response_model_exclude: Optional[IncEx] = None,
|
|
response_model_by_alias: bool = True,
|
|
response_model_exclude_unset: bool = False,
|
|
response_model_exclude_defaults: bool = False,
|
|
response_model_exclude_none: bool = False,
|
|
include_in_schema: bool = True,
|
|
response_class: Union[Type[Response], DefaultPlaceholder] = Default(
|
|
JSONResponse
|
|
),
|
|
name: Optional[str] = None,
|
|
openapi_extra: Optional[Dict[str, Any]] = None,
|
|
generate_unique_id_function: Callable[[routing.APIRoute], str] = Default(
|
|
generate_unique_id
|
|
),
|
|
) -> None:
|
|
self.router.add_api_route(
|
|
path,
|
|
endpoint=endpoint,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
methods=methods,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def api_route(
|
|
self,
|
|
path: str,
|
|
*,
|
|
response_model: Any = Default(None),
|
|
status_code: Optional[int] = None,
|
|
tags: Optional[List[Union[str, Enum]]] = None,
|
|
dependencies: Optional[Sequence[Depends]] = None,
|
|
summary: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
response_description: str = "Successful Response",
|
|
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
|
|
deprecated: Optional[bool] = None,
|
|
methods: Optional[List[str]] = None,
|
|
operation_id: Optional[str] = None,
|
|
response_model_include: Optional[IncEx] = None,
|
|
response_model_exclude: Optional[IncEx] = None,
|
|
response_model_by_alias: bool = True,
|
|
response_model_exclude_unset: bool = False,
|
|
response_model_exclude_defaults: bool = False,
|
|
response_model_exclude_none: bool = False,
|
|
include_in_schema: bool = True,
|
|
response_class: Type[Response] = Default(JSONResponse),
|
|
name: Optional[str] = None,
|
|
openapi_extra: Optional[Dict[str, Any]] = None,
|
|
generate_unique_id_function: Callable[[routing.APIRoute], str] = Default(
|
|
generate_unique_id
|
|
),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
def decorator(func: DecoratedCallable) -> DecoratedCallable:
|
|
self.router.add_api_route(
|
|
path,
|
|
func,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
methods=methods,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
return func
|
|
|
|
return decorator
|
|
|
|
def add_api_websocket_route(
|
|
self,
|
|
path: str,
|
|
endpoint: Callable[..., Any],
|
|
name: Optional[str] = None,
|
|
*,
|
|
dependencies: Optional[Sequence[Depends]] = None,
|
|
) -> None:
|
|
self.router.add_api_websocket_route(
|
|
path,
|
|
endpoint,
|
|
name=name,
|
|
dependencies=dependencies,
|
|
)
|
|
|
|
def websocket(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
WebSocket path.
|
|
"""
|
|
),
|
|
],
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A name for the WebSocket. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
*,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be used for this
|
|
WebSocket.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
|
|
"""
|
|
),
|
|
] = None,
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Decorate a WebSocket function.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI, WebSocket
|
|
|
|
app = FastAPI()
|
|
|
|
@app.websocket("/ws")
|
|
async def websocket_endpoint(websocket: WebSocket):
|
|
await websocket.accept()
|
|
while True:
|
|
data = await websocket.receive_text()
|
|
await websocket.send_text(f"Message text was: {data}")
|
|
```
|
|
"""
|
|
|
|
def decorator(func: DecoratedCallable) -> DecoratedCallable:
|
|
self.add_api_websocket_route(
|
|
path,
|
|
func,
|
|
name=name,
|
|
dependencies=dependencies,
|
|
)
|
|
return func
|
|
|
|
return decorator
|
|
|
|
def include_router(
|
|
self,
|
|
router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")],
|
|
*,
|
|
prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to all the *path operations* in this
|
|
router.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to all the
|
|
*path operations* in this router.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import Depends, FastAPI
|
|
|
|
from .dependencies import get_token_header
|
|
from .internal import admin
|
|
|
|
app = FastAPI()
|
|
|
|
app.include_router(
|
|
admin.router,
|
|
dependencies=[Depends(get_token_header)],
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses to be shown in OpenAPI.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).
|
|
|
|
And in the
|
|
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark all the *path operations* in this router as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
from .internal import old_api
|
|
|
|
app = FastAPI()
|
|
|
|
app.include_router(
|
|
old_api.router,
|
|
deprecated=True,
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = None,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include (or not) all the *path operations* in this router in the
|
|
generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
from .internal import old_api
|
|
|
|
app = FastAPI()
|
|
|
|
app.include_router(
|
|
old_api.router,
|
|
include_in_schema=False,
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = True,
|
|
default_response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Default response class to be used for the *path operations* in this
|
|
router.
|
|
|
|
Read more in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
|
|
|
|
**Example**
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from fastapi.responses import ORJSONResponse
|
|
|
|
from .internal import old_api
|
|
|
|
app = FastAPI()
|
|
|
|
app.include_router(
|
|
old_api.router,
|
|
default_response_class=ORJSONResponse,
|
|
)
|
|
```
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> None:
|
|
"""
|
|
Include an `APIRouter` in the same app.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/).
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
from .users import users_router
|
|
|
|
app = FastAPI()
|
|
|
|
app.include_router(users_router)
|
|
```
|
|
"""
|
|
self.router.include_router(
|
|
router,
|
|
prefix=prefix,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
include_in_schema=include_in_schema,
|
|
default_response_class=default_response_class,
|
|
callbacks=callbacks,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def get(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP GET operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.get("/items/")
|
|
def read_items():
|
|
return [{"name": "Empanada"}, {"name": "Arepa"}]
|
|
```
|
|
"""
|
|
return self.router.get(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def put(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP PUT operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from pydantic import BaseModel
|
|
|
|
class Item(BaseModel):
|
|
name: str
|
|
description: str | None = None
|
|
|
|
app = FastAPI()
|
|
|
|
@app.put("/items/{item_id}")
|
|
def replace_item(item_id: str, item: Item):
|
|
return {"message": "Item replaced", "id": item_id}
|
|
```
|
|
"""
|
|
return self.router.put(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def post(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP POST operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from pydantic import BaseModel
|
|
|
|
class Item(BaseModel):
|
|
name: str
|
|
description: str | None = None
|
|
|
|
app = FastAPI()
|
|
|
|
@app.post("/items/")
|
|
def create_item(item: Item):
|
|
return {"message": "Item created"}
|
|
```
|
|
"""
|
|
return self.router.post(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def delete(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP DELETE operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.delete("/items/{item_id}")
|
|
def delete_item(item_id: str):
|
|
return {"message": "Item deleted"}
|
|
```
|
|
"""
|
|
return self.router.delete(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def options(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP OPTIONS operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.options("/items/")
|
|
def get_item_options():
|
|
return {"additions": ["Aji", "Guacamole"]}
|
|
```
|
|
"""
|
|
return self.router.options(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def head(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP HEAD operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI, Response
|
|
|
|
app = FastAPI()
|
|
|
|
@app.head("/items/", status_code=204)
|
|
def get_items_headers(response: Response):
|
|
response.headers["X-Cat-Dog"] = "Alone in the world"
|
|
```
|
|
"""
|
|
return self.router.head(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def patch(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP PATCH operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from pydantic import BaseModel
|
|
|
|
class Item(BaseModel):
|
|
name: str
|
|
description: str | None = None
|
|
|
|
app = FastAPI()
|
|
|
|
@app.patch("/items/")
|
|
def update_item(item: Item):
|
|
return {"message": "Item updated in place"}
|
|
```
|
|
"""
|
|
return self.router.patch(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def trace(
|
|
self,
|
|
path: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The URL path to be used for this *path operation*.
|
|
|
|
For example, in `http://example.com/items`, the path is `/items`.
|
|
"""
|
|
),
|
|
],
|
|
*,
|
|
response_model: Annotated[
|
|
Any,
|
|
Doc(
|
|
"""
|
|
The type to use for the response.
|
|
|
|
It could be any valid Pydantic *field* type. So, it doesn't have to
|
|
be a Pydantic model, it could be other things, like a `list`, `dict`,
|
|
etc.
|
|
|
|
It will be used for:
|
|
|
|
* Documentation: the generated OpenAPI (and the UI at `/docs`) will
|
|
show it as the response (JSON Schema).
|
|
* Serialization: you could return an arbitrary object and the
|
|
`response_model` would be used to serialize that object into the
|
|
corresponding JSON.
|
|
* Filtering: the JSON sent to the client will only contain the data
|
|
(fields) defined in the `response_model`. If you returned an object
|
|
that contains an attribute `password` but the `response_model` does
|
|
not include that field, the JSON sent to the client would not have
|
|
that `password`.
|
|
* Validation: whatever you return will be serialized with the
|
|
`response_model`, converting any data as necessary to generate the
|
|
corresponding JSON. But if the data in the object returned is not
|
|
valid, that would mean a violation of the contract with the client,
|
|
so it's an error from the API developer. So, FastAPI will raise an
|
|
error and return a 500 error code (Internal Server Error).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
|
|
"""
|
|
),
|
|
] = Default(None),
|
|
status_code: Annotated[
|
|
Optional[int],
|
|
Doc(
|
|
"""
|
|
The default status code to be used for the response.
|
|
|
|
You could override the status code by returning a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
|
|
"""
|
|
),
|
|
] = None,
|
|
tags: Annotated[
|
|
Optional[List[Union[str, Enum]]],
|
|
Doc(
|
|
"""
|
|
A list of tags to be applied to the *path operation*.
|
|
|
|
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/#tags).
|
|
"""
|
|
),
|
|
] = None,
|
|
dependencies: Annotated[
|
|
Optional[Sequence[Depends]],
|
|
Doc(
|
|
"""
|
|
A list of dependencies (using `Depends()`) to be applied to the
|
|
*path operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
|
|
"""
|
|
),
|
|
] = None,
|
|
summary: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A summary for the *path operation*.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
A description for the *path operation*.
|
|
|
|
If not provided, it will be extracted automatically from the docstring
|
|
of the *path operation function*.
|
|
|
|
It can contain Markdown.
|
|
|
|
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/).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_description: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The description for the default response.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = "Successful Response",
|
|
responses: Annotated[
|
|
Optional[Dict[Union[int, str], Dict[str, Any]]],
|
|
Doc(
|
|
"""
|
|
Additional responses that could be returned by this *path operation*.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
deprecated: Annotated[
|
|
Optional[bool],
|
|
Doc(
|
|
"""
|
|
Mark this *path operation* as deprecated.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
operation_id: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Custom operation ID to be used by this *path operation*.
|
|
|
|
By default, it is generated automatically.
|
|
|
|
If you provide a custom operation ID, you need to make sure it is
|
|
unique for the whole API.
|
|
|
|
You can customize the
|
|
operation ID generation with the parameter
|
|
`generate_unique_id_function` in the `FastAPI` class.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_include: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to include only certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_exclude: Annotated[
|
|
Optional[IncEx],
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to exclude certain fields in the
|
|
response data.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = None,
|
|
response_model_by_alias: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response model
|
|
should be serialized by alias when an alias is used.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_model_exclude_unset: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that were not set and
|
|
have their default values. This is different from
|
|
`response_model_exclude_defaults` in that if the fields are set,
|
|
they will be included in the response, even if the value is the same
|
|
as the default.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_defaults: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data
|
|
should have all the fields, including the ones that have the same value
|
|
as the default. This is different from `response_model_exclude_unset`
|
|
in that if the fields are set but contain the same default values,
|
|
they will be excluded from the response.
|
|
|
|
When `True`, default values are omitted from the response.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
|
|
"""
|
|
),
|
|
] = False,
|
|
response_model_exclude_none: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Configuration passed to Pydantic to define if the response data should
|
|
exclude fields set to `None`.
|
|
|
|
This is much simpler (less smart) than `response_model_exclude_unset`
|
|
and `response_model_exclude_defaults`. You probably want to use one of
|
|
those two instead of this one, as those allow returning `None` values
|
|
when it makes sense.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
|
|
"""
|
|
),
|
|
] = False,
|
|
include_in_schema: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
Include this *path operation* in the generated OpenAPI schema.
|
|
|
|
This affects the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
|
|
"""
|
|
),
|
|
] = True,
|
|
response_class: Annotated[
|
|
Type[Response],
|
|
Doc(
|
|
"""
|
|
Response class to be used for this *path operation*.
|
|
|
|
This will not be used if you return a response directly.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
|
|
"""
|
|
),
|
|
] = Default(JSONResponse),
|
|
name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Name for this *path operation*. Only used internally.
|
|
"""
|
|
),
|
|
] = None,
|
|
callbacks: Annotated[
|
|
Optional[List[BaseRoute]],
|
|
Doc(
|
|
"""
|
|
List of *path operations* that will be used as OpenAPI callbacks.
|
|
|
|
This is only for OpenAPI documentation, the callbacks won't be used
|
|
directly.
|
|
|
|
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
|
|
"""
|
|
),
|
|
] = None,
|
|
openapi_extra: Annotated[
|
|
Optional[Dict[str, Any]],
|
|
Doc(
|
|
"""
|
|
Extra metadata to be included in the OpenAPI schema for this *path
|
|
operation*.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
|
|
"""
|
|
),
|
|
] = None,
|
|
generate_unique_id_function: Annotated[
|
|
Callable[[routing.APIRoute], str],
|
|
Doc(
|
|
"""
|
|
Customize the function used to generate unique IDs for the *path
|
|
operations* shown in the generated OpenAPI.
|
|
|
|
This is particularly useful when automatically generating clients or
|
|
SDKs for your API.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
|
|
"""
|
|
),
|
|
] = Default(generate_unique_id),
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a *path operation* using an HTTP TRACE operation.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.put("/items/{item_id}")
|
|
def trace_item(item_id: str):
|
|
return None
|
|
```
|
|
"""
|
|
return self.router.trace(
|
|
path,
|
|
response_model=response_model,
|
|
status_code=status_code,
|
|
tags=tags,
|
|
dependencies=dependencies,
|
|
summary=summary,
|
|
description=description,
|
|
response_description=response_description,
|
|
responses=responses,
|
|
deprecated=deprecated,
|
|
operation_id=operation_id,
|
|
response_model_include=response_model_include,
|
|
response_model_exclude=response_model_exclude,
|
|
response_model_by_alias=response_model_by_alias,
|
|
response_model_exclude_unset=response_model_exclude_unset,
|
|
response_model_exclude_defaults=response_model_exclude_defaults,
|
|
response_model_exclude_none=response_model_exclude_none,
|
|
include_in_schema=include_in_schema,
|
|
response_class=response_class,
|
|
name=name,
|
|
callbacks=callbacks,
|
|
openapi_extra=openapi_extra,
|
|
generate_unique_id_function=generate_unique_id_function,
|
|
)
|
|
|
|
def websocket_route(
|
|
self, path: str, name: Union[str, None] = None
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
def decorator(func: DecoratedCallable) -> DecoratedCallable:
|
|
self.router.add_websocket_route(path, func, name=name)
|
|
return func
|
|
|
|
return decorator
|
|
|
|
@deprecated(
|
|
"""
|
|
on_event is deprecated, use lifespan event handlers instead.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
|
|
"""
|
|
)
|
|
def on_event(
|
|
self,
|
|
event_type: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The type of event. `startup` or `shutdown`.
|
|
"""
|
|
),
|
|
],
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add an event handler for the application.
|
|
|
|
`on_event` is deprecated, use `lifespan` event handlers instead.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).
|
|
"""
|
|
return self.router.on_event(event_type)
|
|
|
|
def middleware(
|
|
self,
|
|
middleware_type: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The type of middleware. Currently only supports `http`.
|
|
"""
|
|
),
|
|
],
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add a middleware to the application.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/).
|
|
|
|
## Example
|
|
|
|
```python
|
|
import time
|
|
|
|
from fastapi import FastAPI, Request
|
|
|
|
app = FastAPI()
|
|
|
|
|
|
@app.middleware("http")
|
|
async def add_process_time_header(request: Request, call_next):
|
|
start_time = time.time()
|
|
response = await call_next(request)
|
|
process_time = time.time() - start_time
|
|
response.headers["X-Process-Time"] = str(process_time)
|
|
return response
|
|
```
|
|
"""
|
|
|
|
def decorator(func: DecoratedCallable) -> DecoratedCallable:
|
|
self.add_middleware(BaseHTTPMiddleware, dispatch=func)
|
|
return func
|
|
|
|
return decorator
|
|
|
|
def exception_handler(
|
|
self,
|
|
exc_class_or_status_code: Annotated[
|
|
Union[int, Type[Exception]],
|
|
Doc(
|
|
"""
|
|
The Exception class this would handle, or a status code.
|
|
"""
|
|
),
|
|
],
|
|
) -> Callable[[DecoratedCallable], DecoratedCallable]:
|
|
"""
|
|
Add an exception handler to the app.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).
|
|
|
|
## Example
|
|
|
|
```python
|
|
from fastapi import FastAPI, Request
|
|
from fastapi.responses import JSONResponse
|
|
|
|
|
|
class UnicornException(Exception):
|
|
def __init__(self, name: str):
|
|
self.name = name
|
|
|
|
|
|
app = FastAPI()
|
|
|
|
|
|
@app.exception_handler(UnicornException)
|
|
async def unicorn_exception_handler(request: Request, exc: UnicornException):
|
|
return JSONResponse(
|
|
status_code=418,
|
|
content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
|
|
)
|
|
```
|
|
"""
|
|
|
|
def decorator(func: DecoratedCallable) -> DecoratedCallable:
|
|
self.add_exception_handler(exc_class_or_status_code, func)
|
|
return func
|
|
|
|
return decorator
|