什么是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的实体类型

5.城市列表
URL: /city
Method: get
返回的内容结构为： {flag:true,code:20000, message:"查询成功",data:[{.....},{.....},{.....}]

image.png

实现步骤如下：

6.根据条件查询城市列表

image.png

7. 城市分页列表

实现API效果如下：

实现如下：

整体文档实现如下:

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' 

启动效果如图；

整理不易，喜欢请点赞。

image.png