|
|
|
@ -1740,6 +1740,386 @@ class APIRouter(routing.Router): |
|
|
|
generate_unique_id_function=generate_unique_id_function, |
|
|
|
) |
|
|
|
|
|
|
|
def query( |
|
|
|
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[params.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[[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 APIRouter, FastAPI |
|
|
|
|
|
|
|
app = FastAPI() |
|
|
|
router = APIRouter() |
|
|
|
|
|
|
|
@router.query("/items/") |
|
|
|
def query_items(query: str): |
|
|
|
return { |
|
|
|
"result": {"name": "Empanada", count: 5}, {"name": "Arepa", count: 2}, |
|
|
|
"query": query, |
|
|
|
} |
|
|
|
|
|
|
|
app.include_router(router) |
|
|
|
``` |
|
|
|
""" |
|
|
|
return self.api_route( |
|
|
|
path=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, |
|
|
|
methods=["QUERY"], |
|
|
|
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[ |
|
|
|
|
Alex Kattathra Johnson
1 day ago
GitHub