# Decorators
The primary mechanism for adding content to your schema is by decorating your endpoints. If you have
used sanic-openapi
in the past, this should be familiar to you. The decorators and their arguments match closely
the OAS v3.0 specification (opens new window).
All of the examples show will wrap around a route definition. When you are creating these, you should make sure that
your Sanic route decorator (@app.route
, @app.get
, etc) is the outermost decorator. That is to say that you should
put that first and then one or more of the below decorators after.
from sanic_ext import openapi
@app.get("/path/to/<something>")
@openapi.summary("This is a summary")
@openapi.description("This is a description")
async def handler(request, something: str):
...
You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will
use UserProfile
that will look like this. The point is that it can be any well-typed class. You could easily imagine
this being a dataclass
or some other kind of model object.
class UserProfile:
name: str
age: int
email: str
# Definition decorator
# @openapi.definition
The @openapi.definition
decorator allows you to define all parts of an operations on a path at once. It is an omnibums
decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using
multiple field-specific decorators or a single decorator is a style choice for you the developer.
The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation.
Arguments
Field | Type |
---|---|
body | dict, RequestBody, YourModel |
deprecated | bool |
description | str |
document | str, ExternalDocumentation |
exclude | bool |
operation | str |
parameter | str, dict, Parameter, [str], [dict], [Parameter] |
response | dict, Response, YourModel, [dict], [Response] |
summary | str |
tag | str, Tag, [str], [Tag] |
secured | Dict[str, Any] |
Examples
@openapi.definition(
body=RequestBody(UserProfile, required=True),
summary="User profile update",
tag="one",
response=[Success, Response(Failure, status=400)],
)
See below examples for more examples. Any of the values for the below decorators can be used in the corresponding keyword argument.
# Field-specific decorators
All the following decorators are based on @openapi
# Integration with Pydantic
Pydantic models have the ability to generate OpenAPI schema (opens new window).
To take advantage of Pydantic model schema generation, pass the output in place of the schema.
from sanic import Sanic, json
from sanic_ext import validate, openapi
from pydantic import BaseModel, Field
class Test(BaseModel):
foo: str = Field(description="Foo Description", example="FOOO")
bar: str = "test"
app = Sanic("test")
@app.get("/")
@openapi.definition(
body={'application/json': Test.schema()},
)
@validate(json=Test)
async def get(request):
return json({})
Added in v22.9