The primary mechanism for adding content to your schema is by decorating your endpoints. If you have
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.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, somethind: str): ...
You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will
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 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.
| ||dict, RequestBody, YourModel|
| ||str, ExternalDocumentation|
| ||dict, Parameter, YourModel, [dict], [Parameter], [YourModel]|
| ||dict, Response, YourModel, [dict], [Response], [YourModel]|
| ||str, Tag, [str], [Tag]|
@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