|
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'" |
|
|
|
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 woudln'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, |
|
|
|
websocket_request_validation_exception_handler, |
|
) |
|
|
|
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=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=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 |
|
|