大家好，我是讯享网，很高兴认识大家。



 <p></p> 

讯享网

1. Swagger 简介

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。

依赖坐标

• Springfox Swagger UI

讯享网

• Springfox Swagger2

工程目录及环境介绍

2.1 工程目录

讯享网

2.2 环境介绍

• 操作系统：macOS Catalina 10.15.3
• IDEA：IntelliJ IDEA 2019.1 (Ultimate Edition)
• JDK：1.8
• SpringBoot：2.2.6RELEASE
• Swagger UI：2.9.2
• Swagger2：2.9.2

SpringBoot 集成 Swagger

3.1 新建 SpringBoot 的 Web 项目

3.2 导入上述2个依赖

讯享网

3.3 开启 Swagger

• 新建一个 SwaggerConfig 类
• 添加 @Configuration:表明这是一个配置类
• 开启 Swagger2

3.4 测试 Swagger2 是否启动成功

• 访问：http://localhost:8089/swagger-ui.html

配置 Swagger 信息

4.1 编写配置类

讯享网

4.2 效果

配置扫描接口

在 SwaggerConfig 中对 Docket 对象继续进行设定

• select().apis().paths().build()

重新访问：http://localhost:8089/swagger-ui.html

因为我们指定了映射路径为 /kuang/，所以目前什么接口都没被扫描到

配置是否启动Swagger

• Docket.enable()
• 这里我们设置不启动

6.1 关闭 Swagger

• enable(false)

讯享网

6.2 测试

• 访问 http://localhost:8089/swagger-ui.html

配置 API 文档分组

7.1 配置一个分组

• Docket.groupName()

• 访问： http://localhost:8089/swagger-ui.html

7.2 配置多个分组

• 建立多个 Docket 实例对象

讯享网

• 访问： http://localhost:8089/swagger-ui.html

扫描实体类

8.1 新建一个实体类 User

8.2 Controller 中新加一个方法，返回一个 User 对象

• 只要我们的接口中，返回值存在实体类，它就会被扫描到 Swagger 中

• 访问： http://localhost:8089/swagger-ui.html

8.3 给实体类添加 API 注释

• @ApiModel

讯享网

8.4 给实体类的属性添加 API 注释

• @ApiModelProperty

给控制类添加API注解

9.1 接口添加说明注解

• @ApiOpeartion(value=“接口名”,httpMethod=“请求方式”,notes=“详细说明”)

讯享网

9.2 添加接口参数说明注解

• @ApiImplicitParams 包含多个属性
• @ApiImplicitParam
  • name：属性名
  • value：属性值
  • defaultValue：默认值
  • paramType：表示参数放在哪个地方
    • path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
    • body–>请求参数的获取：@RequestBody(代码中接收注解)
    • form（不常用，form.serilize()）
    query–>请求参数的获取：@RequestParam(代码中接收注解)
  • dataType：参数类型
  • required：是否必须
  header–>请求参数的获取：@RequestHeader(代码中接收注解)

Swagger 的测试功能

10.1 点击”try it out“

10.2 输入参数

10.3 执行查看结果

Swagger 注解总结

11.1 @Api()

• 用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源。
• 参数：

  tags：说明该类的作用，参数是个数组，可以填多个。
  value=“该参数没什么意义，在UI界面上不显示，所以不用配置”
  description = “用户基本信息操作”

11.2 @ApiOperation()

• 用于方法，表示一个http请求访问该方法的操作。
• 参数：

  value=“方法的用途和作用”
  notes=“方法的注意事项和备注”
  tags：说明该方法的作用，参数是个数组，可以填多个。
  格式：tags={“作用1”,“作用2”}
  （在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

11.3 @ApiModel()

• 用于响应实体类上，用于说明实体作用。
• 参数：

  description=“描述实体的作用”

  

11.4 @ApiModelProperty

• 用在属性上，描述实体类的属性
• 参数：

  value=“用户名” 描述参数的意义
  name=“name” 参数的变量名
  required=true 参数是否必选

11.5 @ApiImplicitParams

• 用在请求的方法上，包含多@ApiImplicitParam

11.6 @ApiImplicitParam

• 用于方法，表示单独的请求参数。
• 参数：

  name=“参数ming”

  value=“参数说明”

  dataType=“数据类型”

  ​ -query–>请求参数的获取：@RequestParam(代码中接收注解)

  ​ -path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)

  ​ -body–>请求参数的获取：@RequestBody(代码中接收注解)

  ​ -form（不常用，form.serilize()）

  defaultValue=“参数的默认值”

  required=“true” 表示参数是否必须传

11.7 @ApiParam()

• 用于方法，参数，字段说明 表示对参数的要求和说明。
• 参数：

  name=“参数名称”
  value=“参数的简要说明”
  defaultValue=“参数默认值”
  required=“true” 表示属性是否必填，默认为false

11.8 @ApiResponses

• 用于请求的方法上，根据响应码表示不同响应。
• 一个@ApiResponses包含多个@ApiResponse。

11.9 @ApiResponse

• 用在请求的方法上，表示不同的响应。
• 参数：

11.10 @ApiIgnore()

• 用于类或者方法上，不被显示在页面上。

11.11 @Profile({“dev”, “test”})

• 用于配置类上，表示只对开发和测试环境有用。

项目源码

12.1 SwaggerDemoApplication.java

讯享网

12.2 HelloController.java

12.3 SwaggerConfig.java

讯享网

12.4 User.java

参考资料：

bilibili视频：《狂神说：一小时掌握 Swagger 技术》

知乎：https://zhuanlan.zhihu.com/p/