API

Describes the module API with detailed explanations of functions parameters.

SchemaGenerator

class aiohttp_apischema.SchemaGenerator(info=None)

SchemaGenerator handles the automatic creation of the schema and modifying the app as needed.

First, the SchemaGenerator.api() and SchemaGenerator.api_view() decorators should be applied to any handlers which should be documented.

Second, the SchemaGenerator.setup() method should be called to configure the aiohttp.web.Application object.

Then, on application startup, the SchemaGenerator will finish generating the schema with the finalised route information.

Parameters:

info –

dict-like object that overrides the OpenAPI schema’s info object. The title and version keys are required.

By default the value is {"title": "API", "version": "1.0"}

api(tags=())

Use as a decorator to register a handler function to be part of the API schema.

The handler function must have an APIResponse annotation as the return type and therefore return an instance of this class.

The handler function may have an additional positional parameter (after the request parameter) whose type annotation defines the requestBody type in the schema. When the handler is executed, the request body will be read and validated against that type.

The handler function can define a query keyword-only parameter whose type annotation must be a form of typing.TypedDict. When the handler is executed, the query parameters will be validated against that type.

Parameters:

tags – Sequence of strings used to specify tags to group endpoints.

api_view(tags=())

Use as a decorator to register a aiohttp.web.View class to be part of the API schema. This will register each endpoint method defined in the class.

See SchemaGenerator.api() for more information.

setup(app)

Setup the provided aiohttp.web.Application for schema generation. This will register an aiohttp.web.Application.on_startup function to finalise schema generation.

It also registers a /schema endpoint for serving the schema as JSON and a /swagger/ endpoint for viewing that schema in a Swagger interface.

APIResponse

class aiohttp_apischema.APIResponse(body, *, status=200, reason=None, headers=None, charset=None                     zlib_executor_size=None, zlib_executor=None)

APIResponse is a subclass of aiohttp.web.Response with additional typing information.

The class uses typing.Generic to define the expected output of an API response. The first parameter is used to define the response body type:

APIResponse[int]

The second parameter can be used to define the status code of a response:

APIResponse[int, Literal[201]]

Parameters:

body – This should be a JSONable object of the same type as the first generic parameter. APIResponse will then use json.dumps() to encode the object and return a JSON response, behaving similar to aiohttp.web.json_response().

All other parameters are passed through to aiohttp.web.Response.

Note that mypy, at time of writing, will not infer the typing.Literal when creating an instance. To work around these type errors, the generic parameters must be duplicated:

return APIResponse[int, Literal[201]](42, status=201)

This is not needed when using the default for a 200 response:

return APIResponse(42)