From 87b7d50cfaa26cac582cdcf7d7e3247ec509c9a4 Mon Sep 17 00:00:00 2001 From: "runsha.yan" Date: Fri, 22 Nov 2019 18:34:25 +0800 Subject: [PATCH] 2019.11.22 v1.1.16, update README.rst --- README.rst | 34 ++++++++++++++++---- fishbase/swagger/swagger.py | 64 +++++++++++++++++++++++++++++-------- 2 files changed, 79 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index ebd2e68..e939aa5 100644 --- a/README.rst +++ b/README.rst @@ -39,7 +39,8 @@ fishbase 是由我们自主开发和整理的一套 Python 基础函数库，当 +----------------------------------------------------------------------------------+----------------------------------------+ | `fish_system `_ | 系统增强函数包 | +----------------------------------------------------------------------------------+----------------------------------------+ - +| `swagger `_ | 集成 swagger为flask应用生成接口文档信息| ++----------------------------------------------------------------------------------+----------------------------------------+ 安装 @@ -55,14 +56,32 @@ fishbase 能干什么？ =================== -获取当前系统类型 ----------------------------- +集成 swagger 为 flask 应用生成接口文档信息 +----------------------------------------------- .. code:: python - >>> from fishbase.fish_system import get_platform - >>> print('current os:', get_platform()) - current os: osx + >>> from fishbase.swagger import doc + >>> from fishbase.swagger.swagger import flask_swagger + >>> from flask import Flask + + >>> # 创建 Flask app + >>> app = Flask("Demo Server") + + >>> @app.route('/v1/query', methods=['GET']) + >>> @doc.summary("xx业务查询接口", group="xx业务") + >>> @doc.description("测试 Swagger 使用, 参数为 URL 参数 token, 且必传") + >>> @doc.consumes("token", required=True) + >>> def test_query(): + >>> pass + + >>> # 将 app 对象传递给 swagger 模块 + >>> flask_swagger(app) + + >>> if __name__ == "__main__": + >>> app.run("127.0.0.1", "8899", debug=False) + +访问: http://127.0.0.1:8899/swagger/ 即可查看接口信息，并在线调试。更多 swagger 使用技巧，可参考 https://fishbase.readthedocs.io/en/latest/swagger.html 获取文件的绝对路径 @@ -122,6 +141,9 @@ fishbase 能干什么？ 最近更新 ========== +2019.11.22 v1.1.16 +------------------ +- 为 flask 应用添加 swagger 模块 `#249 `_ 2019.7.17 v1.1.15 ------------------ diff --git a/fishbase/swagger/swagger.py b/fishbase/swagger/swagger.py index 2522aa6..3ee43b1 100644 --- a/fishbase/swagger/swagger.py +++ b/fishbase/swagger/swagger.py @@ -1,5 +1,9 @@ import os +""" +``swagger`` 集成 swagger 为 flask 应用生成接口文档信息。在使用 swagger 前, 应该确保你已经安装了 flask。 + +""" try: from flask import Blueprint, jsonify, render_template except Exception as e: @@ -25,14 +29,25 @@ class SwaggerHelper: @staticmethod def app_is_debug(app): + """ + 判断 flask app 是否以 debug 方式运行。; + + :param: + * 无 + :return: + * bool + """ return getattr(app.config, "DEBUG", True) @staticmethod def get_api_method(rule): """ - 获取路由方法，给每种方法打分，优先级 delete -> patch -> post -> get -> options -> head - :param rule: + 获取路由方法，给每种方法打分，优先级 delete -> patch -> post -> get -> options -> head; + + :param: + * 无 :return: + * str """ method_option = ["delete", "put", "patch", "post", "get", "options", "head"] # 优先级越高,索引最小，返回最高优先级方法 return method_option[min([method_option.index(x.lower()) for x in rule.methods])] @@ -40,8 +55,12 @@ def get_api_method(rule): @staticmethod def consumes_content_types(app, _rule_specs): """ - 入参类型 + 入参格式类型; + + :param: + * 无 :return: + * list(str) """ api_consumes_content_types = app.config.get("API_CONSUMES_CONTENT_TYPES", ["application/json"]) consumes_content_types = ( @@ -52,8 +71,12 @@ def consumes_content_types(app, _rule_specs): @staticmethod def app_name(app): """ - 入参类型 + 获取当前 flask app 的名称，默认为 API; + + :param: + * flask app instance :return: + * str """ app_name = app.config.get("NAME", "API") return app_name @@ -61,10 +84,12 @@ def app_name(app): @staticmethod def produces_content_types(app, _rule_specs): """ - 结果出参格式 - :param app: - :param _rule_specs: + 结果出参格式; + + :param: + * flask app instance, rule :return: + * list(str) """ api_produces_content_types = app.config.get("API_PRODUCES_CONTENT_TYPES", ["application/json"]) produces_content_types = ( @@ -133,9 +158,10 @@ def get_responses(_rule_specs): def flask_swagger(app): """ - flask swagger - :param app: - :return: + 传入 flask app 对象, flask_swagger 会自动收集当前应用的路由信息，并新增 http://ip:port/swagger 调试页面; + + :param: + * flask app instance, rule """ if not SwaggerHelper.app_is_debug(app): return @@ -213,24 +239,36 @@ def flask_swagger(app): def swagger_json(): """ - 返回 json 数据 + 返回当前 flask app 的 swagger 配置信息; + + :param: + * 无 :return: + * json """ return jsonify(_swagger_json) def swagger_config(): """ - 返回 config 数据 + 返回当前 flask app 的 swagger 配置信息; + + :param: + * 无 :return: + * json """ return jsonify(_swagger_config) def swagger(): """ - 返回页面 + 返回当前 flask app 的 swagger 页面信息; + + :param: + * 无 :return: + * """ return render_template("index.html")