API Reference

aiohttp_apispec.setup_aiohttp_apispec(app: aiohttp.web_app.Application, *, title: str = 'API documentation', version: str = '0.0.1', url: str = '/api/docs/swagger.json', request_data_name: str = 'data', swagger_path: str = None, static_path: str = '/static/swagger', error_callback=None, in_place: bool = False, prefix: str = '', schema_name_resolver: Callable = <function resolver>, openapi_version: str = <OpenApiVersion.V20: '2.0'>, **kwargs) → aiohttp_apispec.aiohttp_apispec.AiohttpApiSpec

aiohttp-apispec extension.

Usage:

from aiohttp_apispec import docs, request_schema, setup_aiohttp_apispec
from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')
    bool_field = fields.Bool()


@docs(tags=['mytag'],
      summary='Test method summary',
      description='Test method description')
@request_schema(RequestSchema)
async def index(request):
    return web.json_response({'msg': 'done', 'data': {}})


app = web.Application()
app.router.add_post('/v1/test', index)

# init docs with all parameters, usual for ApiSpec
setup_aiohttp_apispec(app=app,
                      title='My Documentation',
                      version='v1',
                      url='/api/docs/api-docs')

# now we can find it on 'http://localhost:8080/api/docs/api-docs'
web.run_app(app)

Parameters:

• app (Application) – aiohttp web app
• title (str) – API title
• version (str) – API version
• url (str) – url for swagger spec in JSON format
• request_data_name (str) – name of the key in Request object where validated data will be placed by validation_middleware ('data' by default)
• swagger_path (str) – experimental SwaggerUI support (starting from v1.1.0). By default it is None (disabled)
• static_path (str) – path for static files used by SwaggerUI (if it is enabled with swagger_path)
• error_callback – custom error handler
• in_place – register all routes at the moment of calling this function instead of the moment of the on_startup signal. If True, be sure all routes are added to router
• prefix – prefix to add to all registered routes
• schema_name_resolver – custom schema_name_resolver for MarshmallowPlugin.
• openapi_version – version of OpenAPI schema
• kwargs – any apispec.APISpec kwargs

Returns:

return instance of AiohttpApiSpec class

Return type:

AiohttpApiSpec

aiohttp_apispec.docs(**kwargs)

Annotate the decorated view function with the specified Swagger attributes.

Usage:

from aiohttp import web

@docs(tags=['my_tag'],
      summary='Test method summary',
      description='Test method description',
      parameters=[{
              'in': 'header',
              'name': 'X-Request-ID',
              'schema': {'type': 'string', 'format': 'uuid'},
              'required': 'true'
          }]
      )
async def index(request):
    return web.json_response({'msg': 'done', 'data': {}})

aiohttp_apispec.request_schema(schema, location='json', put_into=None, example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.match_info_schema(schema, *, location='match_info', put_into='match_info', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.querystring_schema(schema, *, location='querystring', put_into='querystring', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.form_schema(schema, *, location='form', put_into='form', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.json_schema(schema, *, location='json', put_into='json', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.headers_schema(schema, *, location='headers', put_into='headers', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.cookies_schema(schema, *, location='cookies', put_into='cookies', example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.response_schema(schema, code=200, required=False, description=None)

Add response info into the swagger spec

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class ResponseSchema(Schema):
    msg = fields.Str()
    data = fields.Dict()

@response_schema(ResponseSchema(), 200)
async def index(request):
    return web.json_response({'msg': 'done', 'data': {}})

Parameters:

• description (str) – response description
• required (bool) –
• schema – Schema class or instance
• code (int) – HTTP response code

aiohttp_apispec.use_kwargs(schema, location='json', put_into=None, example=None, add_to_refs=False, **kwargs)

Add request info into the swagger spec and prepare injection keyword arguments from the specified webargs arguments into the decorated view function in request[‘data’] for validation_middleware validation middleware.

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class RequestSchema(Schema):
    id = fields.Int()
    name = fields.Str(description='name')

@request_schema(RequestSchema(strict=True))
async def index(request):
    # aiohttp_apispec_middleware should be used for it
    data = request['data']
    return web.json_response({'name': data['name'],
                              'id': data['id']})

Parameters:

• schema – Schema class or instance
• location – Default request locations to parse
• put_into – name of the key in Request object where validated data will be placed. If None (by default) default key will be used
• example (dict) – Adding example for current schema
• add_to_refs (bool) – Working only if example not None, if True, add example for ref schema. Otherwise add example to endpoint. Default False

aiohttp_apispec.marshal_with(schema, code=200, required=False, description=None)

Add response info into the swagger spec

Usage:

from aiohttp import web
from marshmallow import Schema, fields


class ResponseSchema(Schema):
    msg = fields.Str()
    data = fields.Dict()

@response_schema(ResponseSchema(), 200)
async def index(request):
    return web.json_response({'msg': 'done', 'data': {}})

Parameters:

• description (str) – response description
• required (bool) –
• schema – Schema class or instance
• code (int) – HTTP response code

aiohttp_apispec.validation_middleware(request: aiohttp.web_request.Request, handler) → aiohttp.web_response.Response

Validation middleware for aiohttp web app

Usage:

app.middlewares.append(validation_middleware)