Decorators

Sanic-OpenAPI provides different decorator can help you document your API routes.

Summary

You can add a short summary to your route by using summary() decorator. It is helpful to point out the purpose of your API route.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic("Hello world")
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.summary("Test route")
async def test(request):
    return json({"Hello": "World"})

The summary will show behind the path:

Description

Not only short summary, but also long description of your API route can be addressed by using description() decorator.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.description('This is a test route with detail description.')
async def test(request):
    return json({"Hello": "World"})

To see the description, you have to expand the content of route and it would looks like:

Tag

If you want to group your API routes, you can use tag() decorator to accomplish your need.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.tag("test")
async def test(request):
    return json({"Hello": "World"})

And you can see the tag is change from default to test:

By default, all routes register under Sanic will be tag with default. And all routes under Blueprint will be tag with the blueprint name.

Operation

Sanic-OpenAPI will use route(function) name as the default operationId. You can override the operationId by using operation() decorator. The operation() decorator would be useful when your routes have duplicate name in some cases.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.operation('test1')
async def test(request):
    return json({"Hello": "World"})

Consumes

The consumes() decorator is the most common used decorator in Sanic-OpenAPI. It is used to document the parameter usages in swagger. You can use built-in classes like str, int, dict or use different fields which provides by Sanic-OpenAPI to document your parameters.

There are three kinds of parameter usages:

Query

To document the parameter in query string, you can use location="query" in parameter() decorator. This is also the default to parameter() decorator.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.parameter("filter", str, location="query")
async def test(request):
    return json({"Hello": "World"})

You can expand the contents of route and it will looks like:

When using parameter() with location="query", it only support simple types like str, int but no complex types like dict.

Header

For doucument parameters in header, you can set location="header" with simple types just like location="query".

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


@app.get("/test")
@openapi.parameter("X-API-VERSION", str, location="header", required=True)
async def test(request):
    return json({"Hello": "World"})

It will looks like:

Request Body

In most cases, your APIs might contains lots of parameter in your request body. In Sanic-OpenAPI, you can define them in Python class or use fields which provides by Sanic-OpenAPI to simplify your works.

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


class User:
    name = str


class Test:
    user = User


@app.post("/test")
@openapi.body(
    { "application/json" : Test },
    description="Body description",
    required=True,
)
async def test(request):
    return json({"Hello": "World"})

This will be document like:

Produces

The response() decorator is used to document the default response(with status 200).

from sanic import Sanic
from sanic.response import json

from sanic_openapi import openapi, openapi3_blueprint

app = Sanic()
app.blueprint(openapi3_blueprint)


class Test:
    Hello = openapi.String(description='World')

@app.get("/test")
@openapi.response(200, {"application/json" : Test})
async def test(request):
    return json({"Hello": "World"})

As you can see in this example, you can also use Python class in produces() decorator.