Flask generates swagger documents

flask Automatic generation swagger Of api Interface document

1. install flask-restplus Third party package , Use pip install flask-restplus Can be installed .
2. In an ordinary normal flask Under application project structure , It should be extensions.py Write code under , Because this is the code writing place for program extension . Guide pack , Import flask_restplus Under the Api,Resource,fields. Get one app example . And carry on namespace Writing . The code is as follows ：

    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")

Get an instance Api object ,app Is an instantiated flask object , By instantiating Api When the object passes doc Parameters can specify the route through which the final interface document can be accessed .api.namespace ： It's a namespace , Many interfaces have get,post, The namespace separates them , It can be understood as a blueprint .
path： Represents their routing address , Here they all use route The address of , If you don't write it, you will change the namespace name Add to the front of the routing address
description： It is a general comment on all interfaces under this group .

3. adopt api.model To describe the requested request and Responsive response, adopt api.namespace.parser To describe the requested headers Parameters .

The code example is as follows ：

    #  Use parser  To describe the interface headers  and  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")    #  Use model  To describe the request body of the interface     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")    #  Use model  To describe the response of the interface     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")    })

Above , among bar_line yes api.namespace() The return object of , Use parser Of add_argument() Method to add headers , or query Request required parameters in , You can also define default values .
Use model To describe the body of the request , The response is also .model You need to specify a unique key value , And a {} Dictionary key value pairs , In the dictionary key value pair key The value is the value to be transmitted name,value It's through flask-restplus Under the fields To specify the data type and default value description Value .
If fields The data type provided in cannot meet the requirements of , You can inherit through custom classes fields.Row , And realize format Method , To use custom data types . In code DictItem Custom data types .

4. The above defined model,parser Apply to the interface . By means of ornaments , The code is as follows .

    #  Use api.namespace.route  To specify the access route of the interface , Use description To describe the interface     @bar_line.route('/api/chart/draw/bar_and_line',                    doc={"description": " Returns the of the chart echarts  Configuration item information , When the request parameter configuration is empty, the chart of the default configuration is returned, which is an example , Otherwise, the corresponding complete chart configuration information is returned according to the requested configuration parameters "})    #  there api.namespace.expect  Need to work with the above api.namespace.expect  In combination with     @bar_line.expect(bar_line_parameter)    #  Need to inherit from Resource class     class BarLineOption(Resource):        # doc  Used to describe interfaces ,body=X  Specify the requested body describe         @bar_line.doc('Return to bar and line chart configuration item')        @bar_line.doc(body=bar_line_model)        # marshal_with  Specifies the description of the response         @bar_line.marshal_with(bar_line_response)        #  What methods does the interface support , Just define a method .        def post(self):            return {'data': {},                    "status": 200, "msg": "successful"}