Skip to main content

APISpec support for starlette

Project description

Easy APISpec integration for Starlette
Travis Codecov PyPI PyPI - Python Version
from apispec import APISpec
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=["apispec.ext.marshmallow"],
    )
)

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: 0.39.0

Usage

This example includes marshmallow integration

from apispec import APISpec

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=["apispec.ext.marshmallow"],
    )
)
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!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for starlette-apispec, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size starlette_apispec-0.1.3-py3-none-any.whl (5.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size starlette-apispec-0.1.3.tar.gz (4.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page