前后端分离缺陷
了解Swagger之前,需要先知道什么是前后端分离
现在的时代
SpringBoot + VUE 以前的时代
SSM + JSP模板引擎====>后端程序员 前后端分离时代
通过相关的API接口进行交互 前后端相对独立,松耦合 前后端可以分别部署在不同的服务器上 伪造后端交互数据,json数据已经存在,不需要后端传入json数据了,前端工程已经可以运行 后端:后端控制层 + 服务层 + 数据访问层 前端:前端控制层 + 视图层 前后端如何交互? 但这样会产生新问题
前后端集成联调,前端和后端开发人员无法做到 及时协商,尽早解决问题
,就会导致项目延期解决方案:
前端测试后端:postMan 后端提供接口,需要实时更新最新的消息和改动 首先指定schema[计划大纲],团队实时更新最新的API,可以降低集成的风险; 早些年:指定world计划文档 前后端分离:
Swagger简介
Swagger官网
号称世界上最流行的API框架 RestFul API文档在线生成工具--->>>==API文档与API同步更新== 可以直接运行,可以在线测试API接口 支持多种语言:(Java,PHP......)
使用SpringBoot集成Swagger
-
创建 SpringBoot-Web
项目,导入相关依赖
注意事项:
在项目中使用Swagger需要SpringBox swagger2 swaggerui
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
-
创建hello程序
扩展,一个hello程序有两个请求,一个是
SpringBoot
项目默认的/error
@RestController
public class HelloController {
/**
* 测试Controller
*
* @return
*/
@GetMapping("/hello")
public String hello() {
return "你好呀!!!Swagger";
}
}
-
配置 Swagger
,新建SwaggerConfig
@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
}
-
测试运行
唯一地址:
http://localhost:8080/swagger-ui.html
配置Swagger信息
-
修改 SwaagerConfig
package com.mobai.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* Software:IntelliJ IDEA 2020.1 x64
* Author: MoBai·杰
* Date: 2020/6/11 13:33
* ClassName:SwaggerConfig
* 类描述:Swagger配置类
*/
@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
/**
* 配置Swagger信息
*
* @return
*/
private ApiInfo apiInfo() {
// 配置作者信息
Contact contact = new Contact("墨白",
"https://www.mobaijun.com",
"[email protected]");
// 配置API文档标题
return new ApiInfo("框架师Api",
// API文档描述
"Api Documentation",
// API版本号
"1.0",
// 配置URL(公司官网/blog地址)
"https://www.mobaijun.com",
// 作者信息
contact,
// 以下内容默认即可
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger配置扫描接口
Docket.select();
-
在 SawggerConfig
配置类完善配置扫描接口的参数
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置扫描接口
.select()
/*
*RequestHandlerSelectors,配置要扫描接口的方式
* 参数说明:
* basePackage:基于包扫描
* class:基于类扫描
* any():扫描全部
* none():全部都不扫描
* withMethodAnnotation:通过方法的注解扫描
* // withMethodAnnotation(GetMapping.class))
* withClassAnnotation:通过类的注解扫描
*/
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
// .paths()过滤,不扫描哪些接口
.paths(PathSelectors.any())
.build();
}
-
配置 Swagger
启动
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置Swagger是否启动,默认:true
.enable(false)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
小测试:如果有一个需求,需要你判断在生成环境中使用,在发布的时候不使用
开发思路
先判断.enable()是不是等于 false
注入Enable(flag)
-
实现,添加
application-dev.properties生产环境配置和application-pro.properties发布环境配置
-
默认
application.properties
环境配置添加
# 开启profiles.active监听,dev测试环境,pro发布环境
spring.profiles.active=dev
-
生产环境修改端口号
server.port=8081
-
发布环境修改端口号
server.port=8082
-
SwaggerConfig
配置类判断当前环境
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
配置API文档的分组
-
配置多个组,添加 .groupName()
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置分组
.groupName("墨白小组")
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
-
效果
-
配置多个组
@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
/**
* 添加A组
* 每个组各司其职
*
* @return
*/
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
/**
* 添加B组
*
* @return
*/
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
/**
* 添加C组
*
* @return
*/
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置分组
.groupName("墨白小组")
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
-
效果
-
实体类配置
@ApiModel("用户实体类") // 添加注释
public class User {
// 添加注释
@ApiModelProperty("年龄")
private Integer age;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("账号")
private String username;
@ApiModelProperty("密码")
private String password;
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
-
效果
-
Swagger常用注解
-
@ApiModel("注释")
:实体类添加注释 -
@ApiModelProperty("注释")
:给实体类属性添加注释 -
@ApiOperation("注释")
给接口(Controller)方法添加注释,放在方法上 -
@ApiParam("")
给方法的参数添加注释 -
@Api("")
给类添加注释 -
controller
package com.mobai.swagger.controller;
import com.mobai.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Software:IntelliJ IDEA 2020.1 x64
* Author: MoBai·杰
* Date: 2020/6/11 13:25
* ClassName:HelloController
* 类描述: 测试类
*/
@ApiOperation("")
@RestController
public class HelloController {
/**
* 测试Controller
*
* @return
*/
@GetMapping("/hello")
public String hello() {
return "你好呀!!!Swagger";
}
/**
* 只要我们的接口中,返回值存在实体类,Swagger就会扫描到
*
* @return
*/
@PostMapping("/user")
public User user() {
return new User();
}
@ApiOperation("Post测试类")
@PostMapping(value = "/post")
public User post(@ApiParam("用户对象") User user) {
return user;
}
}
-
总结
-
添加 @Configuration
注解,标识配置类 -
添加 @EnableSwagger2
注解开启Swagger -
Swagger2
-
Swagger-ui
-
创建SpringBoot项目,导入 Swagger
依赖 -
创建 Swagger
配置类 -
配置 Swagger
的Docket
的Bean
实例 -
配置 Swagger
信息 -
我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
-
接口文档实时更新
-
可以在线测试
-
Swagger是一个优秀的工具,几乎所有的大公司都在用
-
需要注意:正式发布的时候,关闭swagger!!!出于安全考虑,而且节省运行内存!
感谢阅读,如果有帮助到你,请转发,点击再看,这是我分享的动力,感谢
本文分享自微信公众号 - 框架师(mohu121)。
如有侵权,请联系 [email protected] 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。