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": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Valetov Konstantin",
"author_email": "forjob@thetrue.name",
"download_url": "https://files.pythonhosted.org/packages/5e/f0/7a304d4bf3e08833e05b1f57e0d7f1e07884444aa275b3f50aa0aefa56ce/aiohttp_swagger3-0.9.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.9.0",
"project_urls": {
"Homepage": "https://github.com/hh-h/aiohttp-swagger3"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f8029cf4667cf9dcf9f425236b74029507da362f3094b2ce9e333f2e7193545",
"md5": "01d685d5063e0e9b86e9feaa56411476",
"sha256": "59889571aef43a0a64d2202c753f49b82a0342ab7c3ff899603b5f99961d3a6f"
},
"downloads": -1,
"filename": "aiohttp_swagger3-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01d685d5063e0e9b86e9feaa56411476",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1796316,
"upload_time": "2024-09-19T03:59:10",
"upload_time_iso_8601": "2024-09-19T03:59:10.478371Z",
"url": "https://files.pythonhosted.org/packages/6f/80/29cf4667cf9dcf9f425236b74029507da362f3094b2ce9e333f2e7193545/aiohttp_swagger3-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ef07a304d4bf3e08833e05b1f57e0d7f1e07884444aa275b3f50aa0aefa56ce",
"md5": "dd3525c6a0e0822bfdf974485135eb1f",
"sha256": "3359e533e349365e12d9117b5e774ec7f79aca44dd116bdb15418d9232fe9ac1"
},
"downloads": -1,
"filename": "aiohttp_swagger3-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "dd3525c6a0e0822bfdf974485135eb1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1808989,
"upload_time": "2024-09-19T03:59:12",
"upload_time_iso_8601": "2024-09-19T03:59:12.791327Z",
"url": "https://files.pythonhosted.org/packages/5e/f0/7a304d4bf3e08833e05b1f57e0d7f1e07884444aa275b3f50aa0aefa56ce/aiohttp_swagger3-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 03:59:12",
"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": [
{
"name": "aiohttp",
"specs": [
[
"<",
"3.11.0"
],
[
">=",
"3.8.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"5.4.0"
]
]
},
{
"name": "attrs",
"specs": [
[
">=",
"19.3.0"
]
]
},
{
"name": "fastjsonschema",
"specs": [
[
">=",
"2.15.0"
],
[
"<",
"2.20.0"
]
]
},
{
"name": "rfc3339-validator",
"specs": [
[
">=",
"0.1.4"
],
[
"<",
"1.0"
]
]
}
],
"tox": true,
"lcname": "aiohttp-swagger3"
}
JSON
