Swagger Editor实例
实例表：
根据第一个表来编写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'
效果：
