使用flasgger对restful添加注释生成api接口文档

利用flasgger生成swagger风格的接口文档，方便前端集成

swagger主要有两种方式，默认生成的时swagger2.0风格

注：swagger跟openapi 3.0冲突，只能选一种风格

swagger 2.0

配置

template = {

  "swagger": "2.0",

  "info": {

    "title": "AdServer API",

    "description": "API for AdServer",

    "contact": {

      "responsibleOrganization": "qs77",

      "responsibleDeveloper": "qs77",

      "email": "qs77@qs77.com",

      "url": "www.qs77.com",

    },

    "termsOfService": "http://www.qs77.net",

    "version": "0.0.1"

  },

  "host": "localhost:12345",  # overrides localhost:500

  "basePath": "/api",  # base bash for blueprint registration

  "schemes": [

    "http",

    # "https"

  ],

  "operationId": "getmyData"

}

swagger = Swagger(app, template=template)

用法

def get(self):

        """

        获取xxxxx

        ---

        tags:

         - Device

        operationId: getDevices

        parameters:

         - in: path

           name: FactoryId

           type: string

           required: false

           description: 设备识别码

         - in: path

           name: CarNumber

           type: string

           required: false

           description: 车牌号

       definitions:
         device:
           type: object
           properties:
             Id:
               type: integer
               description: id
             FactoryId:
               type: string
               description: 设备识别码
             CarNumber:
               type: string
               description: 车牌号

        responses:

         200:

           description: 响应结果

           schema:
             properties:
               code:
                 type: integer
                 description: 错误码
                 default: 2000
               data:
                 type: array
                 items:
                   $ref: '#/definitions/device'
               message:
                 type: string
                 description: 消息

        """

openapi 3.0.3

配置

template = {

  # "swagger": "2.0", 注释掉解决冲突

  "info": {

    "title": "AdServer API",

    "description": "API for AdServer",

    "contact": {

      "responsibleOrganization": "qs77",

      "responsibleDeveloper": "qs77",

      "email": "qs77@qs77.com",

      "url": "www.qs77.com",

    },

    "termsOfService": "http://www.qs77.net",

    "version": "0.0.1"

  },

  "host": "localhost:12345",  # overrides localhost:500

  "basePath": "/api",  # base bash for blueprint registration

  "schemes": [

    "http",

    # "https"

  ],

  "operationId": "getmyData"

}

swagger = Swagger(app, template=template)

app.config['SWAGGER']['openapi'] = '3.0.2'

用法

def get(self):

        """

        获取xxxxx

        ---

        tags:

         - Device

        operationId: getDevices

        parameters:

         - in: path

           name: FactoryId

           type: string

           required: false

           description: 设备识别码

         - in: path

           name: CarNumber

           type: string

           required: false

           description: 车牌号

        components:

          schemas:

            device:

              type: object

              properties:

                Id:

                  type: integer

                  description: id

                FactoryId:

                  type: string

                  description: 设备识别码

                CarNumber:

                  type: string

                  description: 车牌号

        responses:

         200:

           description: 响应结果

           content:

             application/json:

               schema:

                 type: object

                 properties:

                   code:

                     type: integer

                     description: 错误码

                     default: 3000

                   data:

                     type: array

                     items:

                       $ref: '#/components/schemas/device'

                   message:

                     type: string

                     description: 消息

        """