# 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

    MIT Licensed
    Copyright © 2018-present Sanic Community Organization

    ~ Made with ❤️ and ☕️ ~