|Build Status| |docs| |pypi| |python| |license|
Quart-Schema is a Quart extension that provides schema validation and auto-generated API documentation. This is particularly useful when writing RESTful APIs.
Quart-Schema can use either msgspec <https://jcristharif.com/msgspec>
or pydantic <https://docs.pydantic.dev>
to validate.
Quart-Schema can validate an existing Quart route by decorating it
with validate_querystring
, validate_request
, or
validate_response
. It can also validate the JSON data sent and
received over websockets using the send_as
and receive_as
methods.
.. code-block:: python
from dataclasses import dataclass
from datetime import datetime
from quart import Quart, websocket
from quart_schema import QuartSchema, validate_request, validate_response
app = Quart(__name__)
QuartSchema(app)
@dataclass
class Todo:
task: str
due: datetime | None
@app.post("/")
@validate_request(Todo)
@validate_response(Todo, 201)
async def create_todo(data: Todo) -> tuple[Todo, int]:
... # Do something with data, e.g. save to the DB
return data, 201
@app.websocket("/ws")
async def ws() -> None:
while True:
data = await websocket.receive_as(Todo)
... # Do something with data, e.g. save to the DB
await websocket.send_as(data, Todo)
The documentation is served by default at /openapi.json
according
to the OpenAPI standard, or at /docs
for a SwaggerUI <https://swagger.io/tools/swagger-ui/>
interface, or /redocs
for
a redoc <https://github.com/Redocly/redoc>
interface, or
/scalar
for a Scalar <https://github.com/scalar/scalar>
_
interface. Note that there is currently no documentation standard for
WebSockets.
Quart-Schema is developed on GitHub <https://github.com/pgjones/quart-schema>
. If you come across an
issue, or have a feature request please open an issue <https://github.com/pgjones/quart-schema/issues>
. If you want to
contribute a fix or the feature-implementation please do (typo fixes
welcome), by proposing a merge request <https://github.com/pgjones/quart-schema/merge_requests>
_.
Testing
The best way to test Quart-Schema is with `Tox
<https://tox.readthedocs.io>`_,
.. code-block:: console
$ pip install tox
$ tox
this will check the code style and run the tests.
Help
----
The Quart-Schema `documentation
<https://quart-schema.readthedocs.io>`_ is the best places to
start, after that try searching `stack overflow
<https://stackoverflow.com/questions/tagged/quart>`_ or ask for help
`on gitter <https://gitter.im/python-quart/lobby>`_. If you still
can't find an answer please `open an issue
<https://github.com/pgjones/quart-schema/issues>`_.
.. |Build Status| image:: https://github.com/pgjones/quart-schema/actions/workflows/ci.yml/badge.svg
:target: https://github.com/pgjones/quart-schema/commits/main
.. |docs| image:: https://img.shields.io/badge/docs-passing-brightgreen.svg
:target: https://quart-schema.readthedocs.io
.. |pypi| image:: https://img.shields.io/pypi/v/quart-schema.svg
:target: https://pypi.python.org/pypi/Quart-Schema/
.. |python| image:: https://img.shields.io/pypi/pyversions/quart-schema.svg
:target: https://pypi.python.org/pypi/Quart-Schema/
.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg
:target: https://github.com/pgjones/quart-schema/blob/main/LICENSE