1 简介
官网:https://swagger.io/
- Swagger 是一套功能强大且易于使用的 API 开发人员工具套件,适用于团队和个人,支持从设计和文档到测试和部署的整个 API 生命周期的开发。
- Swagger 包含开源、免费和商用工具的组合,允许任何人,从技术工程师到街头智能产品经理,构建每个人都喜欢的令人惊叹的 API。
- Swagger 由 SmartBear Software 构建,SmartBear Software 是团队软件质量工具的领导者。SmartBear 支持软件领域的一些知名人士,包括 Swagger、SoapUI 和 QAComplete。
2 Spring Boot整合Swagger
2.1 依赖和配置文件
pom.xml
<!-- web依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- swagger依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
application.properties
server.port=8800
2.2 Swagger配置类
/**
* 开启Swagger2
*/
public class SwaggerConfig {
}
测试:访问http://localhost:8800/swagger-ui.html
2.3 进阶整合配置一
2.3.1 新建Controller
/**
* @desc: 控制器
* @author: YanMingXin
* @create: 2021/8/2-14:38
**/
public class StudentController {
/**
* Hello World
*
* @return
*/
("/hello")
public String hello() {
return "Hello Swagger";
}
}
2.3.2 配置自定义Docket
/**
* @desc: Swagger配置
* @author: YanMingXin
* @create: 2021/8/2-14:34
**/
public class SwaggerConfig {
/**
* 配置Docket的bean
*
* @return
*/
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
/**
* 配置文档信息(apiInfo)
*
* @return
*/
private ApiInfo apiInfo() {
Contact contact = new Contact("Mr.YanMingXin", "https://blog.***.net/Mr_YanMingXin", "联系人邮箱/博客");
/**
* 参数1:标题
* 参数2:描述
* 参数3:版本
* 参数4:组织链接
* 参数5:联系人信息
* 参数6:许可
* 参数7:许可连接
* 参数8:扩展
*/
return new ApiInfo(
"Spring Boot 整合 Swagger",
"学习Swagger,Spring Boot 整合 Swagger",
"v1.0",
"https://blog.***.net/Mr_YanMingXin",
contact,
"Apache 2.0 许可",
"https://blog.***.net/Mr_YanMingXin",
new ArrayList<>()
);
}
}
2.3.3 测试
访问http://localhost:8800/swagger-ui.html
2.4 进阶配置二
2.4.1 配置分组
/**
* 创建分组
*
* @return
*/
public Docket docketByGroupOne() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 配置分组
.groupName("GroupOne");
}
/**
* 创建分组
*
* @return
*/
public Docket docketByGroupTwo() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 配置分组
.groupName("GroupTwo");
}
2.4.2 配置Model
Models的两种前提条件
- @ApiModel注解
- 在Controller的返回值中的返回类型
Student.java
/**
* @desc: Student实体类
* @author: YanMingXin
* @create: 2021/8/2-14:34
**/
("Student实体类")
public class Student {
("主键")
public Integer sId;
/**
* private修饰会无效
*/
("姓名")
private String sName;
public Student(Integer sId, String sName) {
this.sId = sId;
this.sName = sName;
}
}
StudentController.java
/**
* @desc: 控制器
* @author: YanMingXin
* @create: 2021/8/2-14:38
**/
public class StudentController {
/**
* Hello World
*
* @return
*/
("/hello")
public String hello() {
return "Hello Swagger";
}
/**
* 返回一个Student实体类
*
* @return
*/
("/student")
public Student student() {
return new Student(1, "zs");
}
}
测试:
2.4.3 配置扫描包
/**
* 根据注解扫描
*
* @return
*/
public Docket docketByAnnotation() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("TestStu01")
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller"))
.build();
}
2.4.4 配置Swagger开关
配置分组的开关
public Docket docketOnOrOff() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("Test02")
//配置是否启用Swagger,如果是false,在浏览器将无法访问(只针对于Test02的分组)
.enable(false)
// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/开头的接口
.paths(PathSelectors.ant("/**"))
.build();
}
2.5 进阶配置三
2.5.1 配置皮肤bootstrap-ui
依赖:
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
访问地址:http://localhost:8800/doc.html
2.5.2 配置皮肤Layui-ui
依赖:
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
访问地址:http://localhost:8800/docs.html
2.5.3 配置皮肤mg-ui
依赖:
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>
访问地址:http://localhost:8800/document.html
3 常用注解
Swagger注解 | 简单说明 |
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |