前言
前后端如何交互:API接口
前后端相互独立,松耦合
前后端甚至可以部署在不同的服务器上
前后端集成联调问题
一、Swagger是什么?
1.号称世界上最流行的Api框架
2.RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新
3.直接运行,可以在线测试API接口
4.支持多种语言(Java,Php…)
二、使用步骤及细节
1.maven依赖
1.swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2.ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.配置Swagger=> Config
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
3.配置Swaggerd信息
SwaggerConfig.xml
- Swagger的bean实例Docket,通过配置Docket实例来配置Swaggger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean //配置docket以配置Swagger具体参数
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
}
- 通过apiInfo()属性配置文档信息
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo(
"Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}
- Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
- 重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果
4.配置扫描接口
(链式操作)
通过select()方法配置怎么扫描接口
- 构建Docket时通过select()方法配置怎么扫描接口
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
.build();
}
- 除了包路径配置扫描(basePackage)之外的其他配置扫描方式
RequestHandlerSelectors.any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口(参数是一个注解的反射对象)
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口
- 配置接口扫描过滤
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/abc开头的接口
.paths(PathSelectors.ant("/abc/**"))
.build();
}
其他:
```java
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
5.配置Swagger开关
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select().apis().paths().build();
配置是否启用Swagger,如果是false,在浏览器将无法访问
例:
如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
@Bean
public Docket docket(Environment environment) {
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/abc开头的接口
.paths(PathSelectors.ant("/abc/**"))
.build();
}
application.properties
spring.profiles.active=dev
application-dev.properties
server.port=8081
application-pro.properties
server.port=8082
注:Spring Boot允许通过一定的命名规则(application-{profile}.properties){dev :开发环境、test:测试环境、prod:生产环境}在来定义多个配置文件,然后在application.properties中使用spring.profiles.active来激活一个或者多个配置文件,如果没有指定就会默认启动application-default.properties。
方式 1:在application.properties中添加:
spring.profiles.active = {profile}
方式2:使用spring.profiles.include来叠加profile:
spring.profiles: prod
spring.profiles.include:
- proddb
- prodmq
方式3:通过命令行设置属性值
在命令行运行时,连续的两个 减号 --就是对application.properties中的属性值进行赋值的标识。例如:
java -jar ###.jar --server.port=8088
命令,等价于在application.properties 中添加属性。
而我们可以在项目中设置:
SpringApplication.setAddCommandLineProperties(false);
屏蔽命令行访问属性的设置。
6.配置API分组
- 默认是default。 通过groupName()方法即可配置分组
.groupName("hello") // 配置分组
- 配置多个分组(只需配置多个docket)
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
7.实体配置
- 新建一个实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
- 只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:
@RequestMapping("/getUser")
public User getUser(){
return new User();
}
8.常用注释
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上,修改Handle的描述和详细信息 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
总结
- 可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试
- Swagger其实就是在管理Controller中的Handle所对应的接口,后端人员只需要引入Swagger和UI的坐标并在启动类添加@EnableSwagger2注解,前端人员只需要访问 UI页面就可以实时的动态的知晓最新的接口信息, 减少人员沟通, 提升开发效率