什么是Swagger?
着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要， swagger 就是一款让你更好的书写API文档的框架。
如何使用？
1.SwaggerEditor安装与启动
（1）下载 https://github.com/swagger-api/swaggereditor/releases/download/v2.10.4/swagger-editor.zip。
（2）解压swagger-editor,
（3）全局安装http-server(http-server是一个简单的零配置命令行http服务器)
npm install -g http-server
（4）启动swagger-editor
http‐server swagger‐editor
（5）浏览器打开： http://localhost:8080
语法规则
然后我们来举一个例子看如何使用
比如对一个城市的表进行增删改查管理
1.新增城市
编写新增城市的API , post提交城市实体
URL： /city
Method: post
编写后的文档内容如下：
代码实现如下:
2.修改城市
URL： /city/{cityId}
Method: put
编写后的文档内容如下：
代码实现如下:
3.删除城市
删除城市地址为/city/{cityId} ，与修改城市的地址相同，区别在于使用delete方法提交请求
代码实现如下:
4.根据ID查询城市
URL: /city/{cityId}
Method: get
返回的内容结构为： {flag:true,code:20000, message:"查询成功",data: {.....} }
data属性返回的是city的实体类型
代码实现如下：
（1）在definitions下定义城市对象的响应对象
5.城市列表
URL: /city
Method: get
返回的内容结构为： {flag:true,code:20000, message:"查询成功",data:[{.....},{.....},{.....}]
实现步骤如下：
6.根据条件查询城市列表
代码如下：
- 城市分页列表
实现API效果如下：
实现如下：
（2）新增节点
整体文档实现如下:
swagger: '2.0'
info:
version: "1.0.0"
title: 基础模块-城市API
host: localhost:9001
basePath: /
paths:
/city:
post:
summary: 新增城市
parameters:
-
name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 返回城市列表
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/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: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
delete:
summary: 删除城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 根据ID查询城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityResponse'
/city/search:
post:
summary: 根据条件查询城市列表
parameters:
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/search/{page}/{size}:
post:
summary: 根据条件查询城市列表
parameters:
- name: page
in: path
description: 页码
required: true
type: integer
format: int32
- name: size
in: path
description: 页大小
required: true
type: integer
format: int32
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityPageResponse'
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: 返回信息
ApiCityResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/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'
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'
启动效果如图；
整理不易，喜欢请点赞。
