APISpec support for starlette
Project description
==================
Starlette APISpec
==================
Easy APISpec integration for Starlette
.. image:: https://img.shields.io/travis/Woile/starlette-apispec.svg?style=flat-square
:alt: Travis
:target: https://travis-ci.org/Woile/starlette-apispec
.. image:: https://img.shields.io/codecov/c/github/Woile/starlette-apispec.svg?style=flat-square
:alt: Codecov
:target: https://codecov.io/gh/Woile/starlette-apispec
.. image:: https://img.shields.io/pypi/v/starlette-apispec.svg?style=flat-square
:alt: PyPI
:target: https://pypi.org/project/starlette-apispec/
.. image:: https://img.shields.io/pypi/pyversions/starlette-apispec.svg?style=flat-square
:alt: PyPI - Python Version
:target: https://pypi.org/project/starlette-apispec/
.. contents::
:depth: 2
.. code-block:: python
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from starlette.applications import Starlette
from starlette_apispec import APISpecSchemaGenerator
app = Starlette()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
Installation
============
::
pip install -U starlette-apispec
Alternatively you can do
::
poetry add starlette-apispec
About
-----
This library helps you easily document your REST API built with starlette.
`Starlette <https://www.starlette.io/>`_ is a is a lightweight ASGI framework/toolkit,
which is ideal for building high performance asyncio services.
`APISpec <https://apispec.readthedocs.io/en/stable/>`_ supports the `OpenApi Specification <https://github.com/OAI/OpenAPI-Specification>`_
and it has some useful plugins like `marshmallow <https://marshmallow.readthedocs.io/en/3.0/>`_ support.
Version supported: :code:`>=1.0.0b5`
Usage
=====
This example includes `marshmallow <https://marshmallow.readthedocs.io/>`_ integration
.. code-block:: python
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields
from starlette.applications import Starlette
from starlette.endpoints import HTTPEndpoint
from starlette.schemas import OpenAPIResponse
from starlette_apispec import APISpecSchemaGenerator
class UserSchema(Schema):
username = fields.Str(required=True)
app = Starlette()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
app.schema_generator.spec.definition("User", schema=UserSchema)
@app.route("/users", methods=["GET", "HEAD"])
def list_users(request):
"""
responses:
200:
description: A list of users.
schema: UserSchema
examples:
[{"username": "tom"}, {"username": "lucy"}]
"""
raise NotImplementedError()
@app.route("/users", methods=["POST"])
def create_user(request):
"""
responses:
200:
description: A user.
schema: UserSchema
examples:
{"username": "tom"}
"""
raise NotImplementedError()
@app.route("/orgs")
class OrganisationsEndpoint(HTTPEndpoint):
def get(self, request):
"""
responses:
200:
description: A list of organisations.
examples:
[{"name": "Foo Corp."}, {"name": "Acme Ltd."}]
"""
raise NotImplementedError()
def post(self, request):
"""
responses:
200:
description: An organisation.
examples:
{"name": "Foo Corp."}
"""
raise NotImplementedError()
@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
return OpenAPIResponse(app.schema)
More documentation
==================
This package is basically a proxy, so if you wonder how to do something,
here are the sources you need:
`Starlette documentation <https://www.starlette.io/>`_
`APISpec Documentation <https://apispec.readthedocs.io/en/stable/>`_
Testing
=======
1. Clone the repo
2. Install dependencies
::
poetry install
3. Run tests
::
poetry run pytest -s --cov-report term-missing --cov=starlette_apispec tests/
Contributing
============
**PRs are welcome!**
Starlette APISpec
==================
Easy APISpec integration for Starlette
.. image:: https://img.shields.io/travis/Woile/starlette-apispec.svg?style=flat-square
:alt: Travis
:target: https://travis-ci.org/Woile/starlette-apispec
.. image:: https://img.shields.io/codecov/c/github/Woile/starlette-apispec.svg?style=flat-square
:alt: Codecov
:target: https://codecov.io/gh/Woile/starlette-apispec
.. image:: https://img.shields.io/pypi/v/starlette-apispec.svg?style=flat-square
:alt: PyPI
:target: https://pypi.org/project/starlette-apispec/
.. image:: https://img.shields.io/pypi/pyversions/starlette-apispec.svg?style=flat-square
:alt: PyPI - Python Version
:target: https://pypi.org/project/starlette-apispec/
.. contents::
:depth: 2
.. code-block:: python
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from starlette.applications import Starlette
from starlette_apispec import APISpecSchemaGenerator
app = Starlette()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
Installation
============
::
pip install -U starlette-apispec
Alternatively you can do
::
poetry add starlette-apispec
About
-----
This library helps you easily document your REST API built with starlette.
`Starlette <https://www.starlette.io/>`_ is a is a lightweight ASGI framework/toolkit,
which is ideal for building high performance asyncio services.
`APISpec <https://apispec.readthedocs.io/en/stable/>`_ supports the `OpenApi Specification <https://github.com/OAI/OpenAPI-Specification>`_
and it has some useful plugins like `marshmallow <https://marshmallow.readthedocs.io/en/3.0/>`_ support.
Version supported: :code:`>=1.0.0b5`
Usage
=====
This example includes `marshmallow <https://marshmallow.readthedocs.io/>`_ integration
.. code-block:: python
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields
from starlette.applications import Starlette
from starlette.endpoints import HTTPEndpoint
from starlette.schemas import OpenAPIResponse
from starlette_apispec import APISpecSchemaGenerator
class UserSchema(Schema):
username = fields.Str(required=True)
app = Starlette()
app.schema_generator = APISpecSchemaGenerator(
APISpec(
title="Example API",
version="1.0",
openapi_version="3.0.0",
info={"description": "explanation of the api purpose"},
plugins=[MarshmallowPlugin()],
)
)
app.schema_generator.spec.definition("User", schema=UserSchema)
@app.route("/users", methods=["GET", "HEAD"])
def list_users(request):
"""
responses:
200:
description: A list of users.
schema: UserSchema
examples:
[{"username": "tom"}, {"username": "lucy"}]
"""
raise NotImplementedError()
@app.route("/users", methods=["POST"])
def create_user(request):
"""
responses:
200:
description: A user.
schema: UserSchema
examples:
{"username": "tom"}
"""
raise NotImplementedError()
@app.route("/orgs")
class OrganisationsEndpoint(HTTPEndpoint):
def get(self, request):
"""
responses:
200:
description: A list of organisations.
examples:
[{"name": "Foo Corp."}, {"name": "Acme Ltd."}]
"""
raise NotImplementedError()
def post(self, request):
"""
responses:
200:
description: An organisation.
examples:
{"name": "Foo Corp."}
"""
raise NotImplementedError()
@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
return OpenAPIResponse(app.schema)
More documentation
==================
This package is basically a proxy, so if you wonder how to do something,
here are the sources you need:
`Starlette documentation <https://www.starlette.io/>`_
`APISpec Documentation <https://apispec.readthedocs.io/en/stable/>`_
Testing
=======
1. Clone the repo
2. Install dependencies
::
poetry install
3. Run tests
::
poetry run pytest -s --cov-report term-missing --cov=starlette_apispec tests/
Contributing
============
**PRs are welcome!**
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for starlette-apispec-1.0.0b1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 541483204b06f343c4979183520155de0a02acef092a74f1c486c83bdea29083 |
|
MD5 | 4ae7d011e3fc68e9faca8e9d8256c4dc |
|
BLAKE2b-256 | 6c12e11b10caa47d6e4d1a8f31de09364a78e9ad9620947f316043464d90906b |
Close
Hashes for starlette_apispec-1.0.0b1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 41be11173e5ab021df674432ee4c4fef90144ff5600e980190ab3e1e64c71141 |
|
MD5 | 8702e925baed4ee629f2870a5bdf17ea |
|
BLAKE2b-256 | ae741c69fdac4e6f992b8eab93defc434e4eabd22c48ad7f303719ae5e6103fc |