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.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ae5c3e2b779fc94f741f2a09b8b7f884ff4d1844b00e51fd9d101b78a164022 |
|
MD5 | ee00214047ebd9489814e7fdb601f2ba |
|
BLAKE2b-256 | 5dd5ccd5fcd5af752ee51452cbf42c1cc05a0252335b0127df198dce1113d5e4 |