Basics
Note
The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from sanic-openapi
. In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with sanic-openapi
you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does NOT support the OAS2 specification.
Out of the box, Sanic Extensions provides automatically generated API documentation using the v3.0 OpenAPI specification. There is nothing special that you need to do
from sanic import Sanic
app = Sanic("MyApp")
# Add all of your views
After doing this, you will now have beautiful documentation already generated for you based upon your existing application:
Checkout the section on configuration to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the /docs
route.
Using Redoc
or Swagger UI
Changing specification metadata#
If you want to change any of the metada, you should use the describe
method.
In this example dedent
is being used with the description
argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here.
from textwrap import dedent
app.ext.openapi.describe(
"Testing API",
version="1.2.3",
description=dedent(
"""
# Info
This is a description. It is a good place to add some _extra_ doccumentation.
**MARKDOWN** is supported.
"""
),
)