实例表：

根据第一个表来编写Swagger文档

新增城市API：

url:/city
method:post

swagger: '2.0'

info:
  version: 1.0.0
  title: 基础模块-城市API

host: api.tensquare.com
basePath: /base

paths:
  /city:
    post:
      summary: 新增城市
      parameters:
       - name: size
         in: query
         description: size of array
         required: true
         type: number
         format: double
# END ############################################################################
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              title: Person
              type: object
              properties:
                name:
                  type: string
                single:
                  type: boolean
#START 新增定义####################################################################
definitions:
  City:
    type: object
    properties:
      id:
        type: string
        description: ID
      name:
        type: string
        description: 城市名称
      ishot:
        type: string
        description: 是否热门
        
        
      
    
# END 新增定义####################################################################

也可以在下面定义response,然后用schema引入:

swagger: '2.0'

info:
  version: 1.0.0
  title: 基础模块-城市API

host: api.tensquare.com
basePath: /base

paths:
  /city:
    post:
      summary: 新增城市
      parameters:
       - name: body
         in: body
         description: 城市实体类
         required: true
         schema:
          $ref: '#/definitions/City'
# END ############################################################################
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiResponse'
#START 新增定义####################################################################
definitions:
  City:
    type: object
    properties:
      id:
        type: string
        description: ID
      name:
        type: string
        description: 城市名称
      ishot:
        type: string
        description: 是否热门
  ApiResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
        
# END 新增定义####################################################################

修改城市

URL：/city/{cityId}
Method: put

#修改城市#
  /city/{cityId}:
    put:
      summary: 修改城市
      parameters:
       - 
         name: cityId
         in: path
         description: 城市ID
         required: true
         type: string
       - 
         name: body
         in: body
         description: 城市实体类
         required: true
         schema:
          $ref: '#/definitions/City'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiResponse'

删除城市：

URL：/city/{cityId}
Method: delete

#删除城市#
    delete:
      summary: 删除城市
      parameters:
       - 
         name: cityId
         in: path
         description: 城市ID
         required: true
         type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiResponse'   

根据ID查询城市

URL：/city/{cityId}
Method: get
返回的内容结构为: {flag:true,code:2000,message:“查询成功”,data:{{…}}
data属性返回的是city的实体类型
先定义返回类型
代码实现如下：

  ApiCityResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        $ref: '#/definitions/City'

在定义get方法：

#根据id查询城市#            
    get:
      summary: 根据id查询城市
      parameters:
       - 
         name: cityId
         in: path
         description: 城市ID
         required: true
         type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiCityResponse'   

效果：

返回城市列表

URL: /city
Method: get
返回的内容结构为: {flag:true,code:2000,message:“查询成功”,data:[{…},{…},{…}]}
data属性返回的是city的实体数组
定义返回类型

 CityList:
    type: array
    items:
      $ref: '#/definitions/City'
  ApiCityListResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        $ref: '#/definitions/CityList'

get方法：

#返回城市列表 
    get:
      summary: 返回城市列表
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiCityListResponse'
          

效果：

根据条件查询城市列表

URL: /city/search
Method: post

 /city/search:
    post:
      summary: 根据条件查询城市列表
      parameters:
       - name: body
         in: body
         description: 城市实体类
         required: true
         schema:
          $ref: '#/definitions/City'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiCityListResponse'
            

城市分页列表

URL: /city/search/{page}/{size}
Method: post

 ApiCityPageResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        properties: 
          total: 
            type: integer
            format: int32
          rows:
            $ref: '#/definitions/CityList'
    

#分页#
  /city/search/{page}/{size}:
    post:
      summary: 根据条件查询城市列表
      parameters:
       - name: page
         in: path
         description: 页码
         type: integer
         format: int32
         required: true
       - name: size
         in: path
         description: 页大小
         type: integer
         format: int32
         required: true
       - name: body
         in: body
         description: 城市实体类
         required: true
         schema:
          $ref: '#/definitions/City'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ApiCityPageResponse'   

效果：

批量生成API文档