@dataclass
class Example2:
friend: "Cat"
create_cat_docs = EndpointDocs(
request_body=RequestBodyInfo(
description="Example description etc. etc.",
examples={
"fat_cat":
CreateCatInput(
name="Fatty",
active=False,
type=CatType.EUROPEAN,
),
"thin_cat":
CreateCatInput(
name="Thinny",
active=False,
type=CatType.PERSIAN,
),
},
),
responses={
201:
ResponseInfo(
"The cat has been created",
headers={
"Location": HeaderInfo(str, "URL to the new created object")
},
class Cats(ApiController):
@get()
@docs(
parameters={
"page": ParameterInfo(description="Page number"),
},
responses={
HTTPStatus.OK: ResponseInfo(
"A paginated set of Cats",
content=[
ContentInfo(
CatsList,
examples=[
CatsList(
[
Cat(
id=UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"),
name="Foo",
active=True,
type=CatType.EUROPEAN,
creation_time=dateutil_parse(
"2020-10-25T19:39:31.751652"
),
),
Cat(
id=UUID("f212cabf-987c-48e6-8cad-71d1c041209a"),
name="Frufru",
active=True,
type=CatType.PERSIAN,
creation_time=dateutil_parse(
"2020-10-25T19:39:31.751652"
),
),
],
1230,
)
],
)
],
),
"400": "Bad Request",
},
)
def get_cats(
self,
page: FromQuery[int] = FromQuery(1),
page_size: FromQuery[int] = FromQuery(30),
search: FromQuery[str] = FromQuery(""),
) -> Response:
"""
Returns a list of paginated cats.
:param int page: Page number
:param int page_size: Number of items per page
:param str search: Optional search filter
"""
@get("foos")
def get_foos() -> FooList:
...
@get("cats2")
def get_cats_alt2(
self,
page: FromQuery[int] = FromQuery(1),
page_size: FromQuery[int] = FromQuery(30),
search: FromQuery[str] = FromQuery(""),
) -> CatsList:
"""
Alternative way to have the response type for status 200 documented.
Parameters
----------
page : int
Page number.
page_size : int
Number of items per page.
search : str
Optional search filter.
"""
return CatsList(
[
Cat(
id=UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"),
name="Foo",
active=True,
type=CatType.EUROPEAN,
creation_time=dateutil_parse("2020-10-25T19:39:31.751652"),
),
Cat(
id=UUID("f212cabf-987c-48e6-8cad-71d1c041209a"),
name="Frufru",
active=True,
type=CatType.PERSIAN,
creation_time=dateutil_parse("2020-10-25T19:39:31.751652"),
),
],
1230,
)
@docs(
parameters={
"page": ParameterInfo(
"Optional page number (default 1)",
source=ParameterSource.QUERY,
value_type=int,
required=False,
),
"page_size": ParameterInfo(
"Optional page size (default 30)",
source=ParameterSource.QUERY,
value_type=int,
required=False,
),
"search": ParameterInfo(
"Optional search filter",
source=ParameterSource.QUERY,
value_type=str,
required=False,
),
}
)
@get("cats3")
def get_cats_alt3(self, request) -> CatsList:
"""
Note: in this scenario, query parameters can be read from the request object
"""
...
@get("cats4")
def get_cats_alt4(self, request) -> CatsList:
"""
Returns a paginated set of cats.
@param int or None page: Optional page number (default 1).
@param int or None page_size: Optional page size (default 30).
@param str or None search: Optional search filter.
@rtype: CatsList
@return: a paginated set of cats.
"""
...
@post("/foo")
async def update_foo(self, foo_id: UUID, data: UpdateFooInput) -> Foo:
"""
Updates a foo by id.
@param foo_id: the id of the album to update.
@param data: input for the update operation.
"""
@docs(
request_body=RequestBodyInfo(
examples={
"basic": UpdateFooInput(
name="Foo 2",
cool=9000,
etag="aaaaaaaa",
)
},
),
)
@post("/foo2/{foo_id}")
async def update_foo2(
self,
foo_id: UUID,
data: UpdateFooInput,
some_service: FromServices[SomeService],
) -> Foo:
"""
Updates a foo by id.
@param foo_id: the id of the foo to update.
@param data: input for the update operation.
@param some_service: a service injected by dependency injection and used for
some reason.
"""
@docs.ignore()
@get("/ignored")
def secret_api(self):
...
@docs.summary("Some deprecated API")
@docs.deprecated()
@docs.tags("Cats", "Deprecated")
@get("/deprecated")
def deprecated_api(self):
"""
This endpoint is deprecated.
"""
@docs(
summary="Gets a cat by id",
description="""A sample API that uses a petstore as an
example to demonstrate features in the OpenAPI 3 specification""",
responses={
200: ResponseInfo(
"A cat",
content=[
ContentInfo(
Cat,
examples=[
ResponseExample(
Cat(
id=UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"),
name="Foo",
active=True,
type=CatType.EUROPEAN,
creation_time=dateutil_parse(
"2020-10-25T19:39:31.751652"
),
)
)
],
)
],
),
404: "Cat not found",
},
)
@get(":cat_id")
def get_cat(self, cat_id: str) -> Response:
"""
Gets a cat by id.
"""
@post()
@docs(create_cat_docs)
def create_cat(self, input: FromJSON[CreateCatInput]) -> Response:
"""
Creates a new cat.
"""
@post("/variant")
@docs(create_cat_docs)
def post_form(self, input: FromForm[CreateCatInput]) -> Response:
"""
...
"""
@docs(
responses={
204: "Cat deleted successfully",
},
)
@delete(":cat_id")
def delete_cat(self, cat_id: str) -> Response:
"""
Deletes a cat by id.
Lorem ipsum dolor sit amet.
"""
@post("magic")
def magic_cat(self, cat: PydanticExample, foo: Optional[bool]) -> Response:
"""
Creates a magic cat
"""
@post("magic2")
def magic_cat2(self, cat: PydanticExample) -> Response:
"""
Creates a magic cat
"""
@post("magic3")
def magic_cat3(self, example: Example) -> Response:
"""
Creates a magic cat
"""
@post("forward_ref")
def magic_cat4(self, example: Example2) -> Response:
...
@post("poor-use-of-list-annotation")
def magic_cat5(self, example: list) -> Response:
...
@post("poor-use-of-set-annotation2")
def magic_cat6(self, example: Set) -> Response:
...
@post("/polymorph-example")
@docs(on_created=on_polymorph_example_docs_created)
def polymorph_example(self) -> Response:
...
@post("/polymorph-example-pydantic")
@docs(on_created=on_polymorph_example_docs_created_pydantic)
def polymorph_example_pydantic(self) -> Response:
...