Sanic OpenAPI

Give your Sanic API a UI and OpenAPI documentation, all for the price of free!

Installation

pip install sanic-openapi

Add Swagger UI with the OpenAPI spec:

fromsanic_openapiimportswagger_blueprintapp.blueprint(swagger_blueprint)

You'll now have a Swagger UI at the URL /swagger/ and an OpenAPI 2.0 spec at /swagger/swagger.json. Your routes will be automatically categorized by their blueprints.

Example

For an example Swagger UI, see the Pet Store

Usage

Use simple decorators to document routes:

fromsanic_openapiimportdoc@app.get("/user/<user_id:int>")@doc.summary("Fetches a user by ID")@doc.produces({ "user": { "name": str, "id": int } })asyncdefget_user(request, user_id):
...
@app.post("/user")@doc.summary("Creates a user")@doc.consumes(doc.JsonBody({"user": { "name": str }}), location="body")asyncdefcreate_user(request):
...

Model your input/output

classCar:
make=strmodel=stryear=intclassGarage:
spaces=intcars= [Car]
@app.get("/garage")@doc.summary("Gets the whole garage")@doc.produces(Garage)asyncdefget_garage(request):
returnjson({
"spaces": 2,
"cars": [{"make": "Nissan", "model": "370Z"}]
})

Get more descriptive

classCar:
make=doc.String("Who made the car")
model=doc.String("Type of car. This will vary by make")
year=doc.Integer("4-digit year of the car", required=False)
classGarage:
spaces=doc.Integer("How many cars can fit in the garage")
cars=doc.List(Car, description="All cars in the garage")

Specify a JSON body without extensive modelling

garage=doc.JsonBody({
"spaces": doc.Integer,
"cars": [
{
"make": doc.String,
"model": doc.String,
"year": doc.Integer
}
]
})
@app.post("/store/garage")@doc.summary("Stores a garage object")@doc.consumes(garage, content_type="application/json", location="body")asyncdefstore_garage(request):
store_garage(request.json)
returnjson(request.json)

Configure all the things

app.config.API_VERSION='1.0.0'app.config.API_TITLE='Car API'app.config.API_DESCRIPTION='Car API'app.config.API_TERMS_OF_SERVICE='Use with caution!'app.config.API_PRODUCES_CONTENT_TYPES= ['application/json']
app.config.API_CONTACT_EMAIL='channelcat@gmail.com'

Including OpenAPI's host, basePath and security parameters

Just follow the OpenAPI 2.0 specification on this

app.config.API_HOST='subdomain.host.ext'app.config.API_BASEPATH='/v2/api/'app.config.API_SECURITY= [
{
'authToken': []
}
]
app.config.API_SECURITY_DEFINITIONS= {
'authToken': {
'type': 'apiKey', 'in': 'header', 'name': 'Authorization', 'description': 'Paste your auth token and do not forget to add "Bearer " in front of it'
}, 'OAuth2': {
'type': 'oauth2', 'flow': 'application', 'tokenUrl': 'https://your.authserver.ext/v1/token', 'scopes': {
'some_scope': 'Grants access to this API'
}
}
}

Set responses for different HTTP status codes

@app.get("/garage/<id>")@doc.summary("Gets the whole garage")@doc.produces(Garage)@doc.response(404, {"message": str}, description="When the garage cannot be found")asyncdefget_garage(request, id):
garage=some_fetch_function(id)
returnjson(garage)