Skip to content
Easy integration of APISpec for Starlette
Branch: master
Clone or download
Woile Bump version: 1.0.0 → 1.0.1
Made a mistake and removed 1.0.0 from pypi in order to fix syntax
errors in the README.rst.
Latest commit aa0a6bb Feb 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
starlette_apispec Bump version: 1.0.0 → 1.0.1 Feb 16, 2019
tests fix: tests in order to support apispec v1.0.0 Feb 16, 2019
.flake8 feat: added APISpecSchemaGenerator Nov 23, 2018
.gitignore
.travis.yml chore: added travis and changelog Nov 23, 2018
CHANGELOG.md docs: described v1 support Feb 16, 2019
LICENSE Initial commit Nov 23, 2018
README.rst docs: fixed rst syntax errors Feb 16, 2019
pyproject.toml Bump version: 1.0.0 → 1.0.1 Feb 16, 2019

README.rst

Starlette APISpec

Easy APISpec integration for Starlette
Travis Codecov PyPI PyPI - Python Version
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 is a is a lightweight ASGI framework/toolkit, which is ideal for building high performance asyncio services.

APISpec supports the OpenApi Specification and it has some useful plugins like marshmallow support.

Version supported: ^1.0.0

Usage

This example includes marshmallow integration

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

APISpec documentation

Testing

  1. Clone the repo
  2. Install dependencies
poetry install
  1. Run tests
poetry run pytest -s --cov-report term-missing --cov=starlette_apispec tests/

Contributing

PRs are welcome!

You can’t perform that action at this time.