- 前言
- 一：swagger是什么？
- 二：为什么要使用swaager?
-
- 2.1:对于后端开发人员来说
- 2.2:对于前端开发来说
- 2.3：对于测试
- 三：如何搭一个swagger
-
- 3.1:引入swagger的依赖
- 3.2：springBoot整合swagger
- 3.3：swagger的注解
- 四：使用swagger需要注意的问题
一：swagger是什么？
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。
这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。
二：为什么要使用swaager?
2.1:对于后端开发人员来说
- 不用再手写WiKi接口拼大量的参数，避免手写错误
- 对代码侵入性低，采用全注解的方式，开发简单
- 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
- 缺点：增加了开发成本，写接口还得再写一套参数配置
2.2:对于前端开发来说
- 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
- 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题
2.3：对于测试
- 对于某些没有前端界面UI的功能，可以用它来测试接口
- 操作简单，不用了解具体代码就可以操作
- 操作简单，不用了解具体代码就可以操作
三：如何搭一个swagger
3.1:引入swagger的依赖
目前推荐使用2.7.0版本,因为2.6.0版本有bug，而其他版本又没有经过验证
一：引入Swagger依赖库
<!--引入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
四：使用swagger需要注意的问题
- 对于只有一个HttpServletRequest参数的方法,如果参数小于5个，推荐使用 @ApiImplicitParams的方式单独封装每一个参数；如果参数大于5个，采用定义一个对象去封装所有参数的属性，然后使用@APiParam的方式
- 默认的访问地址：ip:port/swagger-ui.html#/,但是在shiro中,会拦截所有的请求，必须加上默认访问路径（比如项目中，就是ip:port/context/swagger-ui.html#/），然后登陆后才可以看到
- 在GET请求中，参数在Body体里面,不能使用@RequestBody。在POST请求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，对于参数转化的配置必须统一
- controller必须指定请求类型，否则swagger会把所有的类型(6种)都生成出来
- swagger在生产环境不能对外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的环境
