目录
如果希望Swagger只在生产环境中使用，在发布时不适用应该怎么做？
Swagger
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
学习目标
了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger
Swagger简介
前后端分离
前后端分离时代：
-
后端：后端控制层、服务层、数据访问层【后端团队】
-
前端：前端控制层、视图层【前端团队】
-
前后端如何交互？ ===》 API
-
前后端相对独立，松耦合
-
前后端甚至可以部署在不同的服务器上
产生一个问题：
-
前后端集成协调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发。
解决方案：
-
首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
-
早些年：指定word计划文档；
-
前后端分离：
-
前端测试后端接口：postman
-
后端提供接口，需要实时更新最新的消息和改动
Swagger
号称世界上最流行的Api框架
RestFul Api 文档在线自动生成工具 ==》 Api文档与API定义同步更新
直接运行，可以在线测试API接口；
支持多种语言：（Java，PHP。。。）
在项目中使用Swagger需要springbox：
-
swagger2
-
ui
SpringBoot集成Swagger
步骤
文字描述：
新建一个SpringBoot = web项目
导入相关依赖
创建一个hello工程进行测试
配置Swagger ==》 config
运行测试 访问 http://localhost:8080/swagger-ui.html 进行测试
详细步骤：
1、新建一个SpringBoot = web项目
2、导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>3、创建一个hello工程进行测试
4、配置Swagger(暂时，集成用)
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
5、运行测试
开启启动类之后，访问地址http://localhost:8080/swagger-ui.html进行运行测试：
swagger-ui页面模块简介
配置Swagger
Swagger的Docket的bean实例
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置Swagger信息 ==》 ApiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wudh", "https://milktearua.top/", "604019297@qq.com");
return new ApiInfo("酒店预订系统API",
"这是一个酒店预订系统的Api",
"v1.0",
"https://milktearua.top/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger配置扫描接口
Docket.select()
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage():指定要扫描的包
//any():扫描全部
//none():都不扫描
//withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.mtr.hotelreservation.controller"))
//paths():过滤什么路径
//any():过滤全部
//none():都不过滤
//regex():正则表达式过滤
//ant():扫描带有某些请求下的接口
.paths(PathSelectors.ant("/mtr/**"))
.build();
}
//配置Swagger信息 ==》 ApiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wudh", "https://milktearua.top/", "604019297@qq.com");
return new ApiInfo("酒店预订系统API",
"这是一个酒店预订系统的Api",
"v1.0",
"https://milktearua.top/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}配置是否启动Swagger
取决于Docket的enable属性，true为启动，false为关闭
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable:是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
.enable(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.mtr.hotelreservation.controller"))
.build();
}当enable属性为false时访问swagger-ui.html页面：
如果希望Swagger只在生产环境中使用，在发布时不适用应该怎么做？
判断是不是生产环境 flag = false
注入enable()的值 enable(flag )
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev");
//获取项目的环境:
//通过environment.acceptsProfiles环境监听的变量，判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage():指定要扫描的包
//any():扫描全部
//none():都不扫描
//withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.mtr.hotelreservation.controller"))
//paths():过滤什么路径
//any():过滤全部
//none():都不过滤
//regex():正则表达式过滤
//ant():扫描带有某些请求下的接口
// .paths(PathSelectors.ant("/mtr/**"))
.build();
}
配置Swagger文档的分组
.groupName()方法来设置分组
如何配置多个分组？
使用多个Docket即可
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.mtr.hotelreservation.controller"))
.build();
}
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
Swagger的实体类配置
只要接口中，返回值存在实体类，它就会被扫描到Swagger中
几个api常用的注释：
//实体类的注释 @ApiModel("用户实体类") public class User {} //实体类属性的注释 @ApiModelProperty("用户名") private String username; //接口的注释 //给接口api增加注释,注意是放在方法上而不是类上 @ApiOperation("Hello接口注释") @GetMapping ("/hello") public String hello(){ return "hello"; } //传入参数的注释 @PostMapping ("/user") public User user(@ApiParam("用户名") String username,@ApiParam("密码") String password){ return new User(String username,String password); }
Swagger的测试功能
总结
我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息。
接口文档实时更新。
可以在线测试。
Swagger是一个优秀的工具，几乎所有大公司都在使用它！
※注意：在正式发布的时候，关闭Swagger！(出于安全考虑，而且节省运行的内存)
欢迎访问我的个人博客:milktearua.top
366
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
