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=ponents(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第三方库
