Skip to main content

APISpec plugin handling Starlette.

Project description

Plugin for APISpec handling Starlette

pypi version Build status Coverage Code style: black Number of tests Number of downloads

This module should not be considered as stable as it is still under development.

However a stable version can be expected by mid March 2020 and any issue or pull request is welcome at any time.

Provides a plugin to use with APISpec to be able to handle Starlette endpoints.

StarlettePlugin usage

from starlette.applications import Starlette
from apispec import APISpec
from apispec_starlette import StarlettePlugin


app = Starlette()
spec = APISpec(
    title="My API",
    version="0.0.1",
    openapi_version="2.0",
    plugins=[StarlettePlugin(app)],
)

Documenting responses inside endpoint docstring

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from apispec import APISpec
from apispec_starlette import StarlettePlugin


app = Starlette()
spec = APISpec(
    title="My API",
    version="0.0.1",
    openapi_version="2.0",
    plugins=[StarlettePlugin(app)],
)


@app.route("/my_endpoint")
def my_endpoint():
    """
    responses:
        200:
            description: "Action performed"
            schema:
                properties:
                    status:
                        type: string
                type: object
    """
    return JSONResponse({"status": "test"})

Documenting responses outside of endpoint docstring

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from apispec import APISpec
from apispec_starlette import StarlettePlugin, document_response


app = Starlette()
spec = APISpec(
    title="My API",
    version="0.0.1",
    openapi_version="2.0",
    plugins=[StarlettePlugin(app)],
)


@app.route("/my_endpoint")
def my_endpoint():
    return JSONResponse({"status": "test"})


document_response(spec, endpoint="/my_endpoint", method="get", status_code=200, response={
    "description": "Action performed",
    "schema": {
        "properties": {"status": {"type": "string"}},
        "type": "object",
    }
})

Documenting OAuth2 security outside of endpoint docstring

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.authentication import AuthenticationMiddleware
from starlette.authentication import requires, AuthenticationBackend
from starlette.responses import JSONResponse
from apispec import APISpec
from apispec_starlette import StarlettePlugin, document_endpoint_oauth2_authentication, document_oauth2_authentication


# TODO Replace by your OAuth2 backend
app = Starlette(middleware=[Middleware(AuthenticationMiddleware, backend=AuthenticationBackend())])
spec = APISpec(
    title="My API",
    version="0.0.1",
    openapi_version="2.0",
    plugins=[StarlettePlugin(app)],
)

# TODO Adjust parameters
document_oauth2_authentication(spec, authorization_url="http://authorization_url", flow="implicit", scopes={"scope1": "Description of scope 1", "scope2": "Description of scope 2"})

@requires(scopes=["scope1", "scope2"])
@app.route("/my_endpoint")
def my_endpoint():
    return JSONResponse({"status": "test"})


document_endpoint_oauth2_authentication(spec, endpoint="/my_endpoint", method="get", required_scopes=["scope1", "scope2"])

Add a /swagger.json endpoint

Your endpoints can be automatically discovered and documented when requesting /swagger.json

from starlette.applications import Starlette
from apispec_starlette import add_swagger_json_endpoint


app = Starlette()
spec = add_swagger_json_endpoint(app=app)

How to install

  1. python 3.6+ must be installed
  2. Use pip to install module:
python -m pip install apispec_starlette

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 apispec-starlette, version 0.0.3
Filename, size File type Python version Upload date Hashes
Filename, size apispec_starlette-0.0.3-py3-none-any.whl (7.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size apispec_starlette-0.0.3.tar.gz (5.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page