Sanic OpenAPI V3e

对sanic的openapi v3支持。记录并描述所有参数，

包括Sanic路径参数。Python3.5+

安装pip install sanic-openapi3e

用法

导入蓝图并使用简单的装饰器来记录路由：importsanicimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)@app.get("/user/")@doc.summary("Fetches a user by ID")@doc.response(200,"The user")asyncdefget_user(request,user_id):returnsanic.response.json(locals())app.go_fast()

现在在url/openapi/spec.json处有一个规范。

你的路线会根据蓝图自动分类

名字。

描述路径参数importsanicimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)@app.get("/examples/test_id/")@doc.parameter(name="an_id",description="An ID",required=True,_in="path")deftest_id(request,an_id):returnsanic.response.json(locals())app.go_fast()

sanic-openapiv3将识别路径参数an_id

用@doc.parameter描述，并将细节合并在一起。

您可能希望指定一个参数仅限于一组选项，

例如星期几或它有最小值。这些都可以做到

对于path、query、header和cookie中的参数：importsanicimportsanic.requestimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)int_min_4=doc.Schema(_type="integer",_format="int32",minimum=4,description="Minimum: 4")@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,)deftest_some_ids(request:sanic.request.Request):query=request.query_stringreturnsanic.response.json(locals())@app.get("/examples/test_id_min/")@doc.parameter(name="an_id",description="An ID",required=True,_in="path",schema=int_min_4)deftest_id_min(request,an_id:int):returnsanic.response.json(locals())app.go_fast()

描述您的标签

openapi使用“标记”(每个路由可以有多个标记)将

终点。很高兴能够将您的端点分组到给定的标记中

根据蓝图的名字，但有时你会想给他们更好的

姓名：@doc.tag("tag name")。最好还是描述一下

对于这些标签(在swagger ui中显示得很好)，所以

@doc.tag("tag name", description="tag description")。

你不必多次添加描述，

sanic-openapiv3e将使其可用，因此

用@doc.tag(...)装饰每个端点，只有其中一个将

需要描述。如果您尝试为

同一个标记，sanic-openapiv3e将引发显示该标记的异常

名称和冲突的描述。

在应用程序中共享和重用常用参数

可能有一些常见的参数出现在

你的API。一周中的几天？最小值必须为的分页

大于零？openapi v3有“组件”的概念，它可以

分享。设置它们很简单：importsanic.requestimportsanic.responsefromsanicimportSanicfromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docdays_of_week=doc.Schema(_type="string",description="Days of the week, short, English",enum=["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],)app=Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)schemas={"int.min4":doc.Schema(title="int.min4",_type="integer",_format="int32",minimum=4,description="Minimum: 4",),"days":days_of_week,}components=doc.Components(schemas=schemas)app.config.OPENAPI_COMPONENTS=components# ^^ the line above adds these to OAS v3's "components"# the next two, which would ordinarily live in your blueprints's module,# reuse these shared components.int_min_4_ref=doc.Reference("#/components/schemas/int.min4")dow_ref=doc.Reference("#/components/schemas/days")@app.get("/simple/01/from//to//in/")@doc.parameter(name="start",description="Start day",required=True,_in="path",schema=dow_ref)@doc.parameter(name="end",description="End day",required=True,_in="path",schema=dow_ref)@doc.parameter(name="hops",description="hops to use",required=True,_in="path",schema=int_min_4_ref,)defget_start_end_hops(request,start:str,end:str,hops:int):returnsanic.response.json(locals())app.go_fast()

不推荐路由路径或参数

参数可以标记为deprecated=True：importsanicimportsanic.requestimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)@app.get("/examples/test_parameter__deprecated/")@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")defparam__deprecated(request,an_id:int):returnsanic.response.json(locals())app.go_fast()

整个路线都可以通过@doc.deprecated：importsanicimportsanic.requestimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)@app.get("/examples/test_path__deprecated/")@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.deprecateddefpath__deprecated(request,an_id:int):returnsanic.response.json(locals())app.go_fast()

排除OpenAPI规范中出现的路由(和虚张声势)

需要软启动一个端点，还是保持你的招摇简单？添加

@doc.exclude而且它根本不在openapi规范中(除非您

当

second将在/openapi/spec.all.json创建规范，它将

所有路线，包括不包括在内。importsanicimportsanic.requestimportsanic.responsefromsanic_openapi3eimportopenapi_blueprint,swagger_blueprint,docapp=sanic.Sanic(strict_slashes=True)app.blueprint(openapi_blueprint)app.blueprint(swagger_blueprint)@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=doc.Schema.Integers,)deftest_some_ids(request:sanic.request.Request):query=request.query_stringreturnsanic.response.json(locals())app.go_fast()

配置一些app.config.API_VERSION='1.0.0'app.config.API_TITLE='An API'app.config.API_DESCRIPTION='An API description'

要有一个contact，请至少设置其中一个(最好是全部)

app.config.API_CONTACT_NAME，

app.config.API_CONTACT_URL或

app.config.API_CONTACT_EMAIL。

有一个license，set app.config.API_LICENSE_NAME和

可选的app.config.API_LICENSE_URL(所有str，但swagger ui除外。

设置termsOfServiceapp.config.API_TERMS_OF_SERVICE_URL(一个str，但是这个招摇的ui

希望将此用作URL)。

设置components、security和externalDocs需要您首先在代码中的某个地方创建相关对象(靠近

在这里创建app)，

设置适当的app.config.OPENAPI_COMPONENTS，

app.config.OPENAPI_SECURITY，

app.config.OPENAPI_EXTERNAL_DOCS。

控制规范生成hide_openapi_self = app.config.get("HIDE_OPENAPI_SELF", True)

show_excluded = app.config.get("SHOW_OPENAPI_EXCLUDED", False)

show_unused_tags = app.config.get("SHOW_OPENAPI_UNUSED_TAGS", False)

实际上，您通常不想记录

/openapi路由，但通过设置app.config.HIDE_OPENAPI_SELF = False

您可以让它们出现在生成的等级库中(因此可以大摇大摆地

也一样)。

您的@doc.exclude注释总是受到尊重的，但是如果您的

配置具有app.config.SHOW_OPENAPI_EXCLUDED = True然后是秒

在/openapi/spec.all.json创建规范。你一般不会想要

这些将在您的生产部署中，但您可能希望它用于dev

以及测试目的。

欢迎加入QQ群-->： 979659372

推荐PyPI第三方库