aiohttp-swagger3
================
.. image:: https://github.com/hh-h/aiohttp-swagger3/actions/workflows/ci.yaml/badge.svg?branch=master
:target: https://github.com/hh-h/aiohttp-swagger3/actions
.. image:: https://img.shields.io/codecov/c/github/hh-h/aiohttp-swagger3/master.svg?style=flat
:target: https://codecov.io/github/hh-h/aiohttp-swagger3?branch=master
.. image:: https://badge.fury.io/py/aiohttp-swagger3.svg
:target: https://badge.fury.io/py/aiohttp-swagger3
.. image:: https://img.shields.io/badge/python-3.7%2B-brightgreen.svg
:target: https://img.shields.io/badge/python-3.7%2B-brightgreen.svg
.. image:: https://img.shields.io/badge/code%20style-black-black.svg
:target: https://github.com/ambv/black
.. image:: https://img.shields.io/pypi/l/aiohttp-swagger3.svg
:target: https://www.apache.org/licenses/LICENSE-2.0
About
=====
Package for displaying swagger docs via different UI backends and
optionally validating/parsing aiohttp requests using swagger
specification 3.0, known as OpenAPI3.
Supported UI backends
=====================
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
Documentation
=============
https://aiohttp-swagger3.readthedocs.io/en/latest/
Disable validation
==================
| 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``
Requirements
============
- python >= 3.8
- aiohttp >= 3.8.0
- pyyaml >= 5.4
- attrs >= 19.3.0
- python-fastjsonschema >= 2.15.0
- rfc3339-validator >= 0.1.4
Limitations
===========
- only application/json and application/x-www-form-urlencoded supported
for now, but you can create own
`handler <https://github.com/hh-h/aiohttp-swagger3/tree/master/examples/custom_handler>`__
- header/query parameters only supported simple/form array
serialization, e.g. 1,2,3,4
- see TODO below
Installation
============
``pip install aiohttp-swagger3``
Example
=======
.. code:: python
from aiohttp import web
from aiohttp_swagger3 import SwaggerDocs, SwaggerInfo, 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/"),
info=SwaggerInfo(
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 <https://github.com/hh-h/aiohttp-swagger3/tree/master/examples>`_
How it helps
============
.. image:: https://raw.githubusercontent.com/hh-h/aiohttp-swagger3/master/docs/_static/comparison.png
Features
========
- 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
- readOnly
- allOf, oneOf, anyOf
- string formats: date, date-time, byte, email, uuid, hostname, ipv4, ipv6
- custom string format validators
TODO (raise an issue if needed)
===============================
- multipleOf
- not
- allowEmptyValue
- Common Parameters for All Methods of a Path (spec file only)
- more serialization methods, see: https://swagger.io/docs/specification/serialization/
- encoding
- form data serialization (array, object)
- default (array, object)
Raw data
{
"_id": null,
"home_page": "https://github.com/hh-h/aiohttp-swagger3",
"name": "aiohttp-swagger3",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Valetov Konstantin",
"author_email": "forjob@thetrue.name",
"download_url": "https://files.pythonhosted.org/packages/9a/b0/73d590d064074026811cbbe1dfc57d4c269049c96f1fd738053b3019496e/aiohttp-swagger3-0.8.0.tar.gz",
"platform": null,
"description": "aiohttp-swagger3\n================\n\n.. image:: https://github.com/hh-h/aiohttp-swagger3/actions/workflows/ci.yaml/badge.svg?branch=master\n :target: https://github.com/hh-h/aiohttp-swagger3/actions\n.. image:: https://img.shields.io/codecov/c/github/hh-h/aiohttp-swagger3/master.svg?style=flat\n :target: https://codecov.io/github/hh-h/aiohttp-swagger3?branch=master\n.. image:: https://badge.fury.io/py/aiohttp-swagger3.svg\n :target: https://badge.fury.io/py/aiohttp-swagger3\n.. image:: https://img.shields.io/badge/python-3.7%2B-brightgreen.svg\n :target: https://img.shields.io/badge/python-3.7%2B-brightgreen.svg\n.. image:: https://img.shields.io/badge/code%20style-black-black.svg\n :target: https://github.com/ambv/black\n.. image:: https://img.shields.io/pypi/l/aiohttp-swagger3.svg\n :target: https://www.apache.org/licenses/LICENSE-2.0\n\nAbout\n=====\n\nPackage for displaying swagger docs via different UI backends and\noptionally validating/parsing aiohttp requests using swagger\nspecification 3.0, known as OpenAPI3.\n\nSupported UI backends\n=====================\n\nMultiple UI backends can be used or UI backend can be disabled at all if only needed\nvalidation without being able to view documentation.\n\n- Swagger UI - https://github.com/swagger-api/swagger-ui\n- ReDoc - https://github.com/Redocly/redoc\n- RapiDoc - https://github.com/mrin9/RapiDoc\n\nDocumentation\n=============\n\nhttps://aiohttp-swagger3.readthedocs.io/en/latest/\n\nDisable validation\n==================\n\n| Pass ``validate=False`` to ``SwaggerDocs``/``SwaggerFile`` class, the default is ``True``\n| Also, sometimes validation has to be disabled for a route,\n to do this you have to pass ``validate=False`` during the initialization of the route.\n| ex. ``web.post(\"/route\", handler, validate=False)``, the default is ``True``\n\nRequirements\n============\n\n- python >= 3.8\n- aiohttp >= 3.8.0\n- pyyaml >= 5.4\n- attrs >= 19.3.0\n- python-fastjsonschema >= 2.15.0\n- rfc3339-validator >= 0.1.4\n\nLimitations\n===========\n\n- only application/json and application/x-www-form-urlencoded supported\n for now, but you can create own\n `handler <https://github.com/hh-h/aiohttp-swagger3/tree/master/examples/custom_handler>`__\n- header/query parameters only supported simple/form array\n serialization, e.g. 1,2,3,4\n- see TODO below\n\nInstallation\n============\n\n``pip install aiohttp-swagger3``\n\nExample\n=======\n\n.. code:: python\n\n from aiohttp import web\n from aiohttp_swagger3 import SwaggerDocs, SwaggerInfo, SwaggerUiSettings\n\n async def get_one_pet(request: web.Request, pet_id: int) -> web.Response:\n \"\"\"\n Optional route description\n ---\n summary: Info for a specific pet\n tags:\n - pets\n parameters:\n - name: pet_id\n in: path\n required: true\n description: The id of the pet to retrieve\n schema:\n type: integer\n format: int32\n responses:\n '200':\n description: Expected response to a valid request\n content:\n application/json:\n schema:\n $ref: \"#/components/schemas/Pet\"\n \"\"\"\n if pet_id not in request.app['storage']:\n raise web.HTTPNotFound()\n return web.json_response(request.app['storage'][pet_id])\n\n def main():\n app = web.Application()\n swagger = SwaggerDocs(\n app,\n swagger_ui_settings=SwaggerUiSettings(path=\"/docs/\"),\n info=SwaggerInfo(\n title=\"Swagger Petstore\",\n version=\"1.0.0\",\n ),\n components=\"components.yaml\"\n )\n swagger.add_routes([\n web.get(\"/pets/{pet_id}\", get_one_pet),\n ])\n app['storage'] = {}\n web.run_app(app)\n\nMore `examples <https://github.com/hh-h/aiohttp-swagger3/tree/master/examples>`_\n\nHow it helps\n============\n\n.. image:: https://raw.githubusercontent.com/hh-h/aiohttp-swagger3/master/docs/_static/comparison.png\n\nFeatures\n========\n\n- application/json\n- application/x-www-form-urlencoded (except array and object)\n- items\n- properties\n- pattern\n- required\n- enum\n- minimum, maximum\n- exclusiveMinimum, exclusiveMaximum\n- minLength, maxLength\n- minItems, maxItems\n- uniqueItems\n- minProperties, maxProperties\n- default (only primitives)\n- additionalProperties\n- nullable\n- readOnly\n- allOf, oneOf, anyOf\n- string formats: date, date-time, byte, email, uuid, hostname, ipv4, ipv6\n- custom string format validators\n\nTODO (raise an issue if needed)\n===============================\n\n- multipleOf\n- not\n- allowEmptyValue\n- Common Parameters for All Methods of a Path (spec file only)\n- more serialization methods, see: https://swagger.io/docs/specification/serialization/\n- encoding\n- form data serialization (array, object)\n- default (array, object)\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "validation for aiohttp swagger openAPI 3",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/hh-h/aiohttp-swagger3"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f1f292b767b5b4f6ca68980fe84df04e9b0a05703751f7ef4f5e90c26facfc0",
"md5": "56f28f6fff2631663abb6a23882cee9e",
"sha256": "c487de95111fc03f735355db084a90d51eb83334b3d3c47f9beb72d1df29ec24"
},
"downloads": -1,
"filename": "aiohttp_swagger3-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56f28f6fff2631663abb6a23882cee9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1796314,
"upload_time": "2023-12-03T13:12:40",
"upload_time_iso_8601": "2023-12-03T13:12:40.244101Z",
"url": "https://files.pythonhosted.org/packages/9f/1f/292b767b5b4f6ca68980fe84df04e9b0a05703751f7ef4f5e90c26facfc0/aiohttp_swagger3-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9ab073d590d064074026811cbbe1dfc57d4c269049c96f1fd738053b3019496e",
"md5": "6022eb31c682b3e9185794852acf7b54",
"sha256": "79009572d4b2fb5ae6252bf68b1909c9523f22cfd5fa2f46add2d5c050cf520c"
},
"downloads": -1,
"filename": "aiohttp-swagger3-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "6022eb31c682b3e9185794852acf7b54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1809078,
"upload_time": "2023-12-03T13:12:42",
"upload_time_iso_8601": "2023-12-03T13:12:42.519639Z",
"url": "https://files.pythonhosted.org/packages/9a/b0/73d590d064074026811cbbe1dfc57d4c269049c96f1fd738053b3019496e/aiohttp-swagger3-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-03 13:12:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hh-h",
"github_project": "aiohttp-swagger3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "aiohttp-swagger3"
}
JSON
