2.2 KiB
2.2 KiB
Security Schemes
To document authentication schemes, there are two steps.
Security is only available starting in v21.12.2
Document the scheme
.. column::
The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as:
```python
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](https://swagger.io/specification/) for details on what values are appropriate.
.. column::
```python
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
.. column::
There are two options, document _all_ endpoints.
.. column::
```python
app.ext.openapi.secured()
app.ext.openapi.secured("token")
```
.. column::
Or, document only specific routes.
.. column::
```python
@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):
...
```