怎么用flask生成swagger文檔

這篇文章主要講解了“怎么用flask生成swagger文檔”，文中的講解內容簡單清晰，易于學習與理解，下面請大家跟著小編的思路慢慢深入，一起來研究和學習“怎么用flask生成swagger文檔”吧！

flask 自動生成swagger 的api接口文檔

1. 安裝flask-restplus 第三方包，使用pip install flask-restplus 安裝即可。

2. 在一個普通的正常的flask 應用項目結構下，應該是在extensions.py 下進行代碼書寫，因為這是進行程序擴展的代碼編寫處。導包，導入flask_restplus 下的Api，Resource，fields。獲取一個app 實例。并進行namespace 的書寫。代碼如下：

    api = Api(doc='/swagger')
    api.init_app(app, version='1.0', title='Data Visualization And Analysis API',
                 description='A Charting and Data analysis API')
    bar_line = api.namespace('drawing bar and line', path='/', description="draw bar and line chart")
    pie = api.namespace('drawing pie', path='/', description="draw pie chart")
    radar = api.namespace('drawing radar', path='/', description="draw radar chart")
    scatter = api.namespace('drawing scatter', path='/', description="draw scatter chart")
    data_analysis = api.namespace('data analysis', path='/', description="data analysis")

獲取一個實例化Api對象，app是一個實例化的flask對象，通過在實例化Api對象時通過doc 參數可以指定最終的接口文檔通過什么路由可以訪問到。api.namespace ：是命名空間，很多接口都有get，post，命名空間把他們分隔開，可理解為藍圖。 path：代表他們的路由地址，這里讓他們都使用route的地址，不寫的話會把命名空間的name加到路由地址的最前面 description：是對該組下所有接口的總的一個注釋。

3. 通過api.model 來描述請求的request 和 響應的response，通過api.namespace.parser 來描述請求的headers 參數。

代碼示例如下：

    # 使用parser 來描述接口的headers 和 query
    bar_line_parameter = bar_line.parser()
    bar_line_parameter.add_argument('Authorization', location='headers', default="a")
    bar_line_parameter.add_argument('User-Agent', location='headers', default="ua")
    # 使用model 來描述接口的請求體
    bar_line_model = api.model('Bar_Line_Request', {
        "type": fields.String(default="bar"),
        "title": DictItem(required=True, default={}, description="chart title option"),
        "item": DictItem(required=True, default={}, description="chart series item option"),
        "xaxis": DictItem(required=True, default={}, description="chart xaxis option"),
        "yaxis": DictItem(required=True, default={}, description="chart yaxis option"),
        "grid": DictItem(required=True, default={}, description="chart grid option"),
        "legend": DictItem(required=True, default={}, description="chart legend option"),
        "tooltip": DictItem(required=True, default={}, description="chart tooltip option"),
        "background": DictItem(required=True, default={}, description="chart tooltip option"),
    }, description="request api needed body parameter")
    # 使用model 來描述接口的響應
    bar_line_response = api.model('bar_line_Response', {
        'data': DictItem(required=True, default=bar_line_response_data_default, description="chart option"),
        'status': fields.Integer(required=True, default=200, description="response status"),
        'msg': fields.String(required=True, default="successful", description="api response message")
    })

如上，其中bar_line 是api.namespace() 的返回對象，使用parser 的add_argument() 方法來添加headers ，或query 中請求所需參數，同時可以定義默認值。 使用model 來描述請求的請求體，響應也是。model 需要指定一個唯一的key 值，和一個 {} 字典鍵值對，在該字典鍵值對中key值是所需傳輸的name，value 是通過flask-restplus 下的fields 來指定數據類型以及默認值描述 的值。 如果fields中提供的數據類型滿足不了使用，可以通過自定義類繼承fields.Row ，并且實現format 方法，來使用自定義的數據類型。代碼中的DictItem 就是自定義數據類型。

4. 將以上定義的model，parser 應用到接口上。通過裝飾器的方式，代碼如下。

    # 使用api.namespace.route 來指定接口的訪問路由，使用description來描述接口
    @bar_line.route('/api/chart/draw/bar_and_line',
                    doc={"description": "返回圖表的echarts 配置項信息，當請求參數配置為空時返回默認配置的圖表即示例樣例，否則根據請求的配置參數返回對應的完整的圖表配置信息"})
    # 這里的api.namespace.expect 需要與上面的api.namespace.expect 聯用
    @bar_line.expect(bar_line_parameter)
    # 需要繼承于Resource類
    class BarLineOption(Resource):
        # doc 用于描述接口，body=X 指定請求的body描述
        @bar_line.doc('Return to bar and line chart configuration item')
        @bar_line.doc(body=bar_line_model)
        # marshal_with 指定響應的描述
        @bar_line.marshal_with(bar_line_response)
        # 接口支持什么方法，就定義一個什么方法。
        def post(self):
            return {'data': {},
                    "status": 200, "msg": "successful"}

感謝各位的閱讀，以上就是“怎么用flask生成swagger文檔”的內容了，經過本文的學習后，相信大家對怎么用flask生成swagger文檔這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關知識點的文章，歡迎關注！