Swagger笔记
1、Swagger简介
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
- 支持在线同步
API文档，不用手动编写API文档。 - 支持
Web页面的在线测试API，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
2、Swagger使用步骤
- 导入依赖
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.1.RELEASE</version>
</dependency>
- 配置
swagger
@Configuration
@EnableSwagger2 // 开启swagger
publicclassSwaggerConfig {
// 这样就可以使用swagger的默认配置
}
- 测试：访问
localhost:8080/swagger-ui.html就可以访问默认的页面
3、Swagger配置信息
// 配置Docket的相关信息
@Bean
publicDocketgetDocket(){
// 文档类型设置为DocumentationType.SWAGGER_2
returnnewDocket(DocumentationType.SWAGGER_2)
// 设置对应的swagger的api信息，参数是一个Contact对象
// 默认是ApiInfo实体类
.apiInfo(this.getApiInfo());
}
/*
默认的信息
static {
DEFAULT = new ApiInfo("Api Documentation",
"Api Documentation", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
*/
privateApiInfogetApiInfo(){
// 文档的作者信息
Contactcontact=newContact("xiaotanke", "http://www.yujiangg.com", "LHJ160414@163.com");
returnnewApiInfo(
// 题目
"测试的Swagger文档",
// 描述
"这是一个测试api文档",
// 版本
"v-1.0",
// 作者网站
"http://www.yujiangg.com",
// 作者的个人信息
contact,
// 开源信息
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
newArrayList()
);
}
4、Swagger配置扫描
swagger默认是扫描项目的全部接口，即扫描项目中的所有controller中的接口，但是我们可以自定义扫描接口。
// 配置Docket的相关信息
@Bean
publicDocketgetDocket(){
// 文档类型设置为DocumentationType.SWAGGER_2
returnnewDocket(DocumentationType.SWAGGER_2)
// 设置对应的swagger的api信息，参数是一个Contact对象
// 默认是ApiInfo实体类
.apiInfo(this.getApiInfo())
// 自定义扫描接口，select()和build()是联合使用的，只能在之间配置
// 两种方式，选择一种
.select()
// apis配置扫描接口范围
/*
basePackage(): 扫描指定包下的接口
any(): 全部扫描，默认全部扫描
none(): 全都不扫描
withMethodAnnotation(): 扫描方法上有指定注解的接口，参数是指定注解的class对象
RequestHandlerSelectors(): 扫描类上有指定注解的接口，参数是指定注解的class对象
*/
// .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
.apis(RequestHandlerSelectors.any())
// .apis(RequestHandlerSelectors.none())
// .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
// .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
// 扫描过滤请求下的接口
/*
ant(): 添加一个过滤请求，扫描这下面的接口
any(): 全部扫描
none(): 全都不扫描
regex(): 扫描满足指定正则的接口
*/
// .paths(PathSelectors.ant("/admin/**"))
// .paths(PathSelectors.any())
// .paths(PathSelectors.none())
.paths(PathSelectors.regex("正则字符串"))
.build();
}
5、Swagger其他配置
- 配置swagger启动
// 配置是否启动，默认是true启动，false不启用
.enable(false)
配置了这个就会出现下面的情况：
应用：将swagger配置成在生产环境中使用，但是上线环境不启动。
- 使用多环境配置，配置
dev(开发)、test(测试)、pro(线上)三种环境。 - 获取项目环境，根据环境判断是否开启swagger。
// 配置Docket的相关信息
@Bean
publicDocketgetDocket(Environmentenvironment){
// 环境
Profilesprofiles=Profiles.of("dev","test");
// acceptsProfiles() 监听项目的环境，参数是Profiles对象，如果存在上面指定的环境名称，就返回true，反之false
booleanflag=environment.acceptsProfiles(profiles);
// 文档类型设置为DocumentationType.SWAGGER_2
returnnewDocket(DocumentationType.SWAGGER_2)
// 设置对应的swagger的api信息，参数是一个Contact对象
// 默认是ApiInfo实体类
.apiInfo(this.getApiInfo())
// 配置是否启动，默认是true启动，false不启用
// 将flag的值作为参数传入，如果是dev或test环境就开启swagger
.enable(flag)
// 自定义扫描接口，select()和build()是联合使用的，只能在之间配置
// 两种方式，选择一种
.select()
// apis配置扫描接口范围
/*
basePackage(): 扫描指定包下的接口
any(): 全部扫描，默认全部扫描
none(): 全都不扫描
withMethodAnnotation(): 扫描方法上有指定注解的接口，参数是指定注解的class对象
RequestHandlerSelectors(): 扫描类上有指定注解的接口，参数是指定注解的class对象
*/
// .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
.apis(RequestHandlerSelectors.any())
// .apis(RequestHandlerSelectors.none())
// .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
// .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
// 扫描过滤请求下的接口
/*
ant(): 添加一个过滤请求，扫描这下面的接口
any(): 全部扫描
none(): 全都不扫描
regex(): 扫描满足指定正则的接口
*/
// .paths(PathSelectors.ant("/admin/**"))
// .paths(PathSelectors.any())
// .paths(PathSelectors.none())
// .paths(PathSelectors.regex("正则字符串"))
.build();
}
6、Swagger分组配置
根据API文档生成多个分组，每个组对应自己的文档。多个组实际就是多个Docket对象，每一个Docket对象就是一个组。
// 组名为B
@Bean
publicDocketgetBDocket(){
returnnewDocket(DocumentationType.SWAGGER_2)
// 组名
.groupName("B");
}
// 组名为C
@Bean
publicDocketgetCDocket(){
returnnewDocket(DocumentationType.SWAGGER_2)
.groupName("C");
}
// 组名为D
@Bean
publicDocketgetDDocket(){
returnnewDocket(DocumentationType.SWAGGER_2)
.groupName("D");
}
7、Swagger注解配置
- 实体类注解
当扫描的接口其中一个返回了一个实体对象，那么在swagger的model中就会有对应实体的内容。
// lombok注解
@Data
@AllArgsConstructor
@NoArgsConstructor
// swagger实体的注释，会在swagger中显示
@ApiModel("用户实体类")
publicclassUser {
// 实体类的字段注释
@ApiModelProperty("自然主键")
privateIntegerid;
@ApiModelProperty("用户名")
privateStringuserName;
@ApiModelProperty("用户密码")
privateStringpassword;
}
- 接口注释
@Controller
publicclassLoginController {
// @ApiOperation 作用于方法上，注释某一个接口
// @ApiParam 作用于参数，用作参数的注释
@ApiOperation("测试接口")
@GetMapping("/test1")
publicStringtest1(@ApiParam("用户名参数") Stringusername){
returnusername;
}
}
- 接口测试
注释注解在作用上就是一个文档的说明，没有实际 上的作用。增强文档的可读性，也便于测试接口。
最近发现除了腾讯云和阿里云之外的一种好用的云服务器，那就是三丰云云服务器，它拥有众多的功能，其中一个就是可以免费试用一款云服务器，下面介绍它的使用方式。
官方地址:https://www.sanfengyun.com/
然后进行一个实名认证和微信的绑定就可以申请一个 1c1g的免费服务器。
三丰云是北京太极三丰云计算有限公司旗下网络服务品牌，十八年IDC老兵团队蛰伏三年后投资千万于2018年10月1日创建。公司致力于为大众提供优质的互联网基础服务和物联网服务，包括：域名注册、虚拟主机、云服务器、主机托管租用、CDN网站加速、物联网应用等服务。以帮助客户轻松、 高速、高效的应用互联网/物联网，提高企业竞争能力。，它拥有众多的功能，其中一个就是可以免费试用一款云服务器，下面介绍它的使用方式。
官方地址:https://www.sanfengyun.com/
