Security Schemes

To document authentication schemes, there are two steps.

Security is only available starting in v21.12.2

Document the scheme#

The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as:

add_security_scheme("<NAME>", "<TYPE>")

The type should correspond to one of the allowed security schemes: "apiKey", "http", "oauth2", "openIdConnect". You can then pass appropriate keyword arguments as allowed by the specification.

You should consult the OpenAPI Specification for details on what values are appropriate.

app.ext.openapi.add_security_scheme("api_key", "apiKey")
app.ext.openapi.add_security_scheme(
    "token",
    "http",
    scheme="bearer",
    bearer_format="JWT",
)
app.ext.openapi.add_security_scheme("token2", "http")
app.ext.openapi.add_security_scheme(
    "oldschool",
    "http",
    scheme="basic",
)
app.ext.openapi.add_security_scheme(
    "oa2",
    "oauth2",
    flows={
        "implicit": {
            "authorizationUrl": "http://example.com/auth",
            "scopes": {
                "on:two": "something",
                "three:four": "something else",
                "threefour": "something else...",
            },
        }
    },
)

Document the endpoints#

There are two options, document all endpoints.

app.ext.openapi.secured()
app.ext.openapi.secured("token")

Or, document only specific routes.

@app.route("/one")
async def handler1(request):
    """
    openapi:
    ---
    security:
        - foo: []
    """

@app.route("/two")
@openapi.secured("foo")
@openapi.secured({"bar": []})
@openapi.secured(baz=[])
async def handler2(request):
    ...

@app.route("/three")
@openapi.definition(secured="foo")
@openapi.definition(secured={"bar": []})
async def handler3(request):
    ...