2019.11.22 v1.1.16, update README.rst

README.rst

@@ -39,7 +39,8 @@ fishbase 是由我们自主开发和整理的一套 Python 基础函数库，当
 +----------------------------------------------------------------------------------+----------------------------------------+
 | `fish_system <https://fishbase.readthedocs.io/en/latest/fish_system.html>`_      | 系统增强函数包                         |
 +----------------------------------------------------------------------------------+----------------------------------------+
-
+| `swagger <https://fishbase.readthedocs.io/en/latest/swagger.html>`_              | 集成 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 <https://github.com/chinapnr/fishbase/issues/249>`_
 
 2019.7.17 v1.1.15
 ------------------

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,23 +29,38 @@ 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])]
 
     @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,19 +71,25 @@ 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
 
     @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")