Package for displaying swagger docs via different UI backends and optionally validating/parsing aiohttp requests using swagger specification 3.0, known as OpenAPI3.
Multiple UI backends can be used or UI backend can be disabled at all if only needed validation without being able to view documentation.
- Swagger UI - https://github.com/swagger-api/swagger-ui
- ReDoc - https://github.com/Redocly/redoc
- RapiDoc - https://github.com/mrin9/RapiDoc
Pass
validate=False
to SwaggerDocs
/SwaggerFile
class, the default is True
Also, sometimes validation has to be disabled for a route,
to do this you have to pass
validate=False
during the initialization of the route.ex.
web.post("/route", handler, validate=False)
, the default is True
- python 3.6+
- aiohttp >= 3.5.4
- pyyaml == 5.3
- attrs == 19.3.0
- python-fastjsonschema == 2.14.3
- strict_rfc3339 == 0.7
- contextvars == 2.4 (for python 3.6 only)
- only application/json and application/x-www-form-urlencoded supported for now, but you can create own handler
- header/query parameters only supported simple/form array serialization, e.g. 1,2,3,4
- see TODO below
pip install aiohttp-swagger3
from aiohttp import web
from aiohttp_swagger3 import SwaggerDocs, SwaggerUiSettings
async def get_one_pet(request: web.Request, pet_id: int) -> web.Response:
"""
Optional route description
---
summary: Info for a specific pet
tags:
- pets
parameters:
- name: pet_id
in: path
required: true
description: The id of the pet to retrieve
schema:
type: integer
format: int32
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
"""
if pet_id not in request.app['storage']:
raise web.HTTPNotFound()
return web.json_response(request.app['storage'][pet_id])
def main():
app = web.Application()
swagger = SwaggerDocs(
app,
swagger_ui_settings=SwaggerUiSettings(path="/docs/"),
title="Swagger Petstore",
version="1.0.0",
components="components.yaml"
)
swagger.add_routes([
web.get("/pets/{pet_id}", get_one_pet),
])
app['storage'] = {}
web.run_app(app)
More examples
- application/json
- application/x-www-form-urlencoded (except array and object)
- items
- properties
- pattern
- required
- enum
- minimum, maximum
- exclusiveMinimum, exclusiveMaximum
- minLength, maxLength
- minItems, maxItems
- uniqueItems
- minProperties, maxProperties
- default (only primitives)
- additionalProperties
- nullable
- allOf, oneOf, anyOf
- string formats: date, date-time, byte, email, uuid, hostname, ipv4, ipv6
- custom string format validators
- multipleOf
- not
- allowEmptyValue
- Common Parameters for All Methods of a Path (spec file only)
- readOnly, writeOnly
- more serialization methods, see: https://swagger.io/docs/specification/serialization/
- encoding
- form data serialization (array, object)
- default (array, object)