API Reference¶

sanic_openapi.doc¶

class sanic_openapi.openapi2.doc.Boolean(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Date(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.DateTime(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Dictionary(fields=None, **kwargs)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Field(description=None, required=None, name=None, choices=None)¶

Bases: object

serialize()¶

class sanic_openapi.openapi2.doc.File(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Float(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Integer(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.JsonBody(fields=None, **kwargs)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.List(items=None, *args, **kwargs)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Object(cls, *args, object_name=None, **kwargs)¶

Bases: sanic_openapi.openapi2.doc.Field

definition¶

serialize()¶

class sanic_openapi.openapi2.doc.RouteField(field, location=None, required=False, description=None)¶

Bases: object

description = None¶

field = None¶

location = None¶

required = None¶

class sanic_openapi.openapi2.doc.RouteSpec¶

Bases: object

blueprint = None¶

consumes = None¶

consumes_content_type = None¶

description = None¶

exclude = None¶

operation = None¶

produces = None¶

produces_content_type = None¶

response = None¶

summary = None¶

tags = None¶

class sanic_openapi.openapi2.doc.String(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

class sanic_openapi.openapi2.doc.Tuple(description=None, required=None, name=None, choices=None)¶: Bases: sanic_openapi.openapi2.doc.Field

class sanic_openapi.openapi2.doc.UUID(description=None, required=None, name=None, choices=None)¶

Bases: sanic_openapi.openapi2.doc.Field

serialize()¶

sanic_openapi.openapi2.doc.consumes(*args, content_type='application/json', location='query', required=False)¶

sanic_openapi.openapi2.doc.description(text)¶

sanic_openapi.openapi2.doc.exclude(boolean)¶

sanic_openapi.openapi2.doc.operation(name)¶

sanic_openapi.openapi2.doc.produces(*args, description=None, content_type=None)¶

sanic_openapi.openapi2.doc.response(*args, description=None)¶

sanic_openapi.openapi2.doc.route(summary=None, description=None, consumes=None, produces=None, consumes_content_type=None, produces_content_type=None, exclude=None, response=None)¶

sanic_openapi.openapi2.doc.serialize_schema(schema)¶

sanic_openapi.openapi2.doc.summary(text)¶

sanic_openapi.openapi2.doc.tag(name)¶

sanic_openapi.api¶

class sanic_openapi.openapi2.api.API¶

Bases: object

Decorator factory class for documenting routes using sanic_openapi and optionally registering them in a sanic application or blueprint.

Supported class attribute names match the corresponding sanic_openapi.doc decorator’s name and attribute values work exactly as if they were passed to the given decorator unless explicitly documented otherwise. The supported class attributes (all of which are optional) are as follows:

summary: Its value should be the short summary of the route. If

neither summary nor description is specified, then the first paragraph of the API class’ documentation will be used instead. You may also set it to None to disable automatic summary and description generation.

description: A longer description of the route. If neither

summary nor description is specified, then the API class’ documentation will be used except its first paragraph that serves as the default summary. You may also set it to None to disable automatic summary and description generation.

exclude: Whether to exclude the route (and related models) from

the API documentation.

consumes: The model of the data the API route consumes. If

consumes is a class that has a docstring, then the docstring will be used as the description of th data.

consumes_content_type: The content type of the data the API route

consumes.

consumes_location: The location where the data is expected

(query or body).

consumes_required: Whether the consumed data is required.

produces: The model of the data the API route produces.

produces_content_type: The content type of the data the API

route produces.

produces_description: The description of the data the API

route produces. If not specified but produces is a class that has a docstring, then the docstring will be used as the default description.

response: A Response instance or a sequence of Response

instances that describe the route’s response for different HTTP status codes. The value of the produces attribute corresponds to HTTP 200, you don’t have to specify that here.

tag: The tags/groups the API route belongs to.

Example:

```Python class JSONConsumerAPI(API):

consumes_content_type = “application/json” consumes_location = “body” consumes_required = True

class JSONProducerAPI(API):

produces_content_type = “application/json”

class MyAPI(JSONConsumerAPI, JSONProducerAPI):

“”” Route summary in first paragraph.

First paragraph of route description.

Second paragraph of route description. “””

class consumes:: foo = str bar = str
class produces:: result = bool

# Document and register the route at once. @MyAPI.post(app, “/my_route”) def my_route(request: Request):

return {“result”: True}

# Or simply document a route. @app.post(“/my_route”) @MyAPI def my_route(request: Request):

return {“result”: True}

```

Additionally, you may specify a decorators class attribute, whose value must be a sequence of decorators to apply on the decorated routes. These decorators will be applied before the sanic_openapi decorators - and the sanic routing decorators if the routing decorators provided by this class are used - in reverse order. It means that the following cases are equivalent:

```Python class Data(API):

class consumes:

stg = str

class DecoratedData(Data):: decorators = (first, second)

@DecoratedData.get(app, “/data”) def data_all_in_one(request: Request):

return “data”

@app.get(“/data”) @DecoratedData def data_doc_and_decorators_in_one(request: Request):

return “data”

@Data.get(app, “/data”) @first @second def data_routing_and_doc_in_one(request: Request):

return “data”

@app.get(“/data”) @Data @first @second def data(request: Request):

return “data”

```

It is possible to override all the described class attributes on a per decorator basis simply by passing the desired custom value to the decorator as a keyword argument:

```Python class JSONConsumerAPI(API):

consumes_content_type = “application/json” consumes_location = “body” consumes_required = True

class consumes:

foo = str bar = str

# The consumed data is required. @JSONConsumerAPI.post(app, “/data”) def data(request: Request):

return “data”

# The consumed data is optional. @app.post(“/data_optional”) @JSONConsumerAPI(consumes_required=False) def data_consumed_not_required(request: Request):

return “data”

```

classmethod delete(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for DELETE requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s delete() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod get(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for GET requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s get() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod head(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for HEAD requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s head() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod options(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for OPTIONS requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s options() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod patch(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for PATCH requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s patch() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod post(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for POST requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s post() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod put(app, uri, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

The decorated method will be registered for PUT requests.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s put() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

classmethod route(app, uri, *, methods, **kwargs)¶

Decorator that registers the decorated route in the given sanic application or blueprint with the given URI, and also documents its API using sanic_openapi.

Keyword arguments that are not listed in arguments section will be passed on to the sanic application’s or blueprint’s route() method as they are.

Arguments:

app: The sanic application or blueprint where the route should: be registered.

uri: The URI the route should be accessible at.

class sanic_openapi.openapi2.api.Response¶

Bases: sanic_openapi.openapi2.api.Response

HTTP status code - returned object model pair with optional description.

If model is a class that has a docstring, the its docstring will be used as description if description is not set.