OpenAPI v3 support for Sanic
Project description
Sanic OpenAPI v3e
Give your Sanic API an OpenAPI v3 specification.
Installation
pip install sanic-openapi3e
Usage
Import blueprint and use simple decorators to document routes:
import sanic
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc
app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)
@app.get("/user/<user_id:int>")
@doc.summary("Fetches a user by ID")
@doc.response(200, "The user")
async def get_user(request, user_id):
return sanic.response.json(locals())
app.go_fast()
You'll now have a specification at the URL /openapi/spec.json
.
Your routes will be automatically categorized by their blueprints'
names.
Configure some of the things
app.config.API_VERSION = '1.0.0'
app.config.API_TITLE = 'An API'
app.config.API_DESCRIPTION = 'An API description'
Other items, like servers, contact, termsOfService are still a work-in-progress.
Describe route path parameters
import sanic
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc
app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)
@app.get("/examples/test_id/<an_id:int>")
@doc.parameter(name="an_id", description="An ID", required=True, _in="path")
def test_id(request, an_id):
return sanic.response.json(locals())
sanic-openapiv3
will recognise that the path parameter an_id
is
described with @doc.parameter
and will merge the details together.
You may wish to specify that a parameter be limited to a set of choices,
such as day-of-week or that it has a minimum value. These can be done
for parameters in path
, query
, header
and cookie
:
import sanic
import sanic.request
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc
app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)
@app.get("/test/some_ids")
@doc.parameter(
name="ids",
description="Some IDs",
required=True,
choices=[1, 3, 5, 7, 11, 13],
_in="query",
schema=doc.Schema.Integers,
)
def test_some_ids(request: sanic.request.Request):
query = request.query_string
return sanic.response.json(locals())
@app.get("/examples/test_id_min/<an_id:int>")
@doc.parameter(
name="an_id", description="An ID", required=True, _in="path", schema=int_min_4
)
def test_id_min(request, an_id: int):
return sanic.response.json(locals())
int_min_4 = doc.Schema(
_type="integer", _format="int32", minimum=4, description="Minimum: 4"
)
Deprecate route paths or parameters
A parameter can be marked as @deprecated()
:
@app.get("/examples/test_parameter__deprecated/<an_id:int>")
@doc.parameter(
name="an_id", description="An ID", required=True, _in="path", deprecated=True
)
@doc.summary("A path deprecated parameter")
@doc.description("The parameter should be marked as deprecated")
def param__deprecated(request, an_id: int):
return sanic.response.json(locals())
as can a whole route:
@app.get("/examples/test_path__deprecated/<an_id:int>")
@doc.parameter(
name="an_id",
description="An ID",
required=True,
_in="path",
)
@doc.summary("A path with parameter examples")
@doc.description("This is marked as being deprecated")
@doc.deprecated()
def path__deprecated(request, an_id: int):
return sanic.response.json(locals())
Exclude routes from appearing in the OpenAPI spec (and swagger)
Need to soft-launch an endpoint, or keep your swagger simple?
@app.get("/test/alpha_release")
@doc.exclude()
@doc.parameter(
name="ids",
description="Some IDs",
required=True,
choices=[1, 3, 5, 7, 11, 13],
_in="query",
schema=oas_types.Schema.Integers,
)
def test_some_ids(request: sanic.request.Request):
query = request.query_string
return sanic.response.json(locals())
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for sanic_openapi3e-0.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3eb602ff6d1a978cb8b84fbee8692692372d9b6efe9bc0d1b5a24c4a850adc8a |
|
MD5 | 185b5e650a927677d079a77fbd1a3da0 |
|
BLAKE2b-256 | 762f1dcd7f24b968c6da1bbc307ad406494f8e7a44aaffffc5891c2ab24828ee |