本文由 简悦 SimpRead 转码， 原文地址 blog.csdn.net
- swagger 介绍
1.1 swagger 介绍及作用
Swagger 是一个接口文档生成工具，同时提供接口测试调用的辅助功能。它可以将项目的所有接口在一个 UI 界面上展示出来，同时表明了这个接口的用途，接口需要的参数是什么类型参数是否必须，输入了参数可以直接测试接口同时会显示接口请求的状态码和返回的数据结构。
Swagger 是一款 RESTFUL 接口的文档在线自动生成 + 功能测试软件。也是一个规范和完整的框架, 用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
swagger 是一款可以根据 Resutful 风格生成的接口开发文档，并且支持做测试的一款中间软件。
1.2 swagger 优点
Swagger 能成为最受欢迎的 Resutful 风格文档生成工具之一，有以下几个原因：
1. Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
2. 大大减少前后端的沟通成本，方便查找和测试接口
3. 提高团队的开发效率
4. 方便新人了解项目
- Spring Boot 集成 swagger
2.1 添加依赖
<!--swagger2核心依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui为项目提供api展示及测试的界面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.2 创建配置类
添加 config 包，创建 SwaggerConfig 自定义的类，添加注解
@Configuration //添加配置
@EnableSwagger2 //开启
public class SwaggerConfig {
}
2.3 配置 swagger
配置 swagger，就需要创建 Bean 实例 Docket
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
//配置appInfo
private ApiInfo apiInfo(){
return new ApiInfo("Api Documentation",
"Api Documentation",
"1.0",
"urn:tos",
new Contact("", "", ""),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
访问路径：http://localhost:8080/swagger-ui.html
2.4 配置 API 文档分组
@Bean
public Docket customDocket() {
return new Docket(
DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("项目一组")
.select()
.apis(RequestHandlerSelectors.basePackage("cn.hxzy.controller"))
.build();
}
3 常用注解及配置扫描接口
swagger2 是通过扫描很多的注解来获取数据帮我们展示在 ui 界面上的，下面就介绍下常用的注解。
1、@ApiModel()：用于响应实体类上，用于说明实体作用
description="描述实体的作用"
2、@ApiModelProperty：用在属性上，描述实体类的属性
value="用户名" 描述参数的描述文本
参数的变量名
required=true 参数是否必选
3、@Api()：用在请求的类（controller）上，表示对类的说明，也代表了这个类是 swagger2 的资源
tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"
4、@ApiOperation()：用于方法，表示一个 http 请求访问该方法的操作
value="方法的用途和作用"
notes="方法的注意事项和备注"
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"}
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）
5、@ApiParam()：用于方法参数，字段说明 表示对参数的要求和说明【单个参数描述】
6、@ApiImplicitParams：用在请求的方法上，包含多 @ApiImplicitParam 【多个参数描述】
7、@ApiImplicitParam：用于方法，表示单独的请求参数
value="参数的简要说明"
defaultValue="参数默认值"
required=true 表示属性是否必填，默认为false
@ApiImplicitParams({
@ApiImplicitParam(name = "userNo",
value = "用户账户",
defaultValue = "admin",
required = true),
@ApiImplicitParam(name = "userPwd",
value = "用户密码",
defaultValue = "123",
required = true),
})
4 swagger 解决了什么
其实归根到底，使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
而 Springfox-swagger, 则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。
-
对于后端开发人员来说
不用再手写接口拼大量的参数，避免手写错误
对代码侵入性低，采用全注解的方式，开发简单
方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
缺点：增加了开发成本，写接口还得再写一套参数配置
-
对于前端开发来说
后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
联调方便，如果出问题，直接测试接口，实时检查参数和返回值, 就可以快速定位是前端还是后端的问题
-
对于测试
对于某些没有前端界面 UI 的功能，可以用它来测试接口
操作简单，不用了解具体代码就可以操作