sanic-openapi3e 0.6.1

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/<user_id:int>")@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处有一个规范。 你的路线会根据蓝图自动分类 名字。

运行这些简单的示例并将浏览器指向 http://127.0.0.1:8000/swagger以查看此操作。

描述路径参数

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/<an_id:int>")@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/<an_id:int>")@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/<start>/to/<end>/in/<hops:int>")@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/<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")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/<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.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 以及测试目的。

标签：

• 路径
• app
• 参数
• doc
• sanic
• 记录
• v3
• openapi
• blueprint

欢迎加入QQ群-->： 979659372

推荐PyPI第三方库

• jusolink

  jusolink api sdk库

• ErplyA

  用于erply api的python包装器

• harissa

  基于机械论的基因网络推理工具

• TempestParser

  tempest解析器工具用于生成各种结果格式的趋势报告：pytest的cli、rally的xml、json、junitxml（支持v4模式）、csv（两种类型）。

• ipfinder-io

  ipfinder的官方python库

• nico-client

  与nicovideo.jp交互的python客户端

• ansiwrap

  文本包装，但精通ANSI颜色和样式

• django-tabulate

  漂亮的印花django querysets。

• TRAPp

  轨迹分析和绘图

• zodburi

  从uri构造zodb存储实例。

• waitfornet

  模块检查您是否在线

• paytm-pg

  Merchant Tuil Library which provide payment，payment status，refund and refund status

• PickALotto

  这个程序可以帮助你随机选择powerball和megamillion的彩票号码

• basket-client

  mozilla篮子服务的python客户端。

• nova-lxd

  openstack的本地lxd驱动程序