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 apispec.ext.marshmallow import MarshmallowPlugin
from starlette.applications import Starlette
from starlette_apispec import APISpecSchemaGenerator

app = Starlette()

schemas = APISpecSchemaGenerator(
    APISpec(
        title="Example API",
        version="1.0",
        openapi_version="3.0.0",
        info={"description": "explanation of the api purpose"},
        plugins=[MarshmallowPlugin()],
    )
)

@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
    return schemas.OpenAPIResponse(request=request)

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 starlette.applications import Starlette
from starlette.endpoints import HTTPEndpoint
from starlette.testclient import TestClient

from starlette_apispec import APISpecSchemaGenerator


app = Starlette()

schemas = APISpecSchemaGenerator(
    APISpec(
        title="Example API",
        version="1.0",
        openapi_version="3.0.0",
        info={"description": "explanation of the api purpose"},
    )
)


@app.websocket_route("/ws")
def ws(session):
    """ws"""
    pass  # pragma: no cover


@app.route("/users", methods=["GET", "HEAD"])
def list_users(request):
    """
    responses:
    200:
        description: A list of users.
        examples:
        [{"username": "tom"}, {"username": "lucy"}]
    """
    pass  # pragma: no cover


@app.route("/users", methods=["POST"])
def create_user(request):
    """
    responses:
    200:
        description: A user.
        examples:
        {"username": "tom"}
    """
    pass  # pragma: no cover


@app.route("/orgs")
class OrganisationsEndpoint(HTTPEndpoint):
    def get(self, request):
        """
        responses:
        200:
            description: A list of organisations.
            examples:
            [{"name": "Foo Corp."}, {"name": "Acme Ltd."}]
        """
        pass  # pragma: no cover

    def post(self, request):
        """
        responses:
        200:
            description: An organisation.
            examples:
            {"name": "Foo Corp."}
        """
        pass  # pragma: no cover


@app.route("/schema", methods=["GET"], include_in_schema=False)
def schema(request):
    return schemas.OpenAPIResponse(request=request)

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. Activate venv . venv/bin/activate
  3. Install dependencies
poetry install
  1. Run tests
./scripts/test

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 1.0.2
Filename, size File type Python version Upload date Hashes
Filename, size starlette_apispec-1.0.2-py3-none-any.whl (5.7 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size starlette-apispec-1.0.2.tar.gz (4.7 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