apispec-starlette 0.0.1

APISpec plugin handling Starlette.

Plugin for APISpec handling Starlette

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",
    }
})

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