1.Spring Boot 集成 Swagger 在线接口文档
1. Swagger 简介
1.1 解决的问题
随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了前后端分离的形态,而且前端技术 和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API
接口,所以
API
文档变成了前后端开发人员联系的纽带,变得越来越重要。那么问题来了,随着代码的不断更新,开发人员在开发新的接口或者更新旧的接口后,由于开发任务的繁重,往往文档很难持续跟着更新,Swagger
就是用来解决该问题的一款重要的工具,对使用接口的人来说,开发人员不需要给他们提供文档,只要告诉一个 Swagger
地址,即可展示在线的
API
接口文档,除此之外,调用接口的人员还可以在线测试接口数据,同样地,开发人员在开发接口时,同样也可以利用 Swagger
在线接口文档测试接口数据,这给开发人员提供了便利。
1.2 Swagger 官方
打开
Swagger
官网为
https://swagger.io/
主要掌握在
Spring Boot
中如何导入
Swagger
工具来展现项目中的接口文档。
2. Swagger 的 maven 依赖
使用
Swagger
工具,必须要导入
maven
依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>
3. Swagger 配置
使用
Swagger
需要进行配置,
Spring Boot
中对
Swagger
的配置非常方便,新建一个配置类,
Swagger
的配置 类上除了添加必要的@Configuration
注解外,还需要添加
@EnableOpenApi
注解。
@EnableOpenApi
@Configuration
public class Swagger3Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
.enable(true)// 是否关闭在线文档,生产环境关闭
apiInfo(apiInfo()) // 指定构建 api 文档的详细信息的方法
.select() // 指定要生成 api 接口的包路径,这里把 action 作为包路径,生成 controller 中的
所有接口 .apis(RequestHandlerSelectors.basePackage("com.yan.action"))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只有在方法接口上添加了 ApiOperation 注解
.paths(PathSelectors.any()).build().globalResponses(HttpMethod.GET, getGlobalResponseMessage())
.globalResponses(HttpMethod.POST, getGlobalResponseMessage());
}
// 生成摘要信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("接口文档") //设置页面标题
.description("说明信息") //设置接口描述
.contact(new Contact("yanjun", "http://baidu.com", "yan@yan.com")) //设置联系方式
.version("1.0") //设置版本
.build(); //构建
}
在该配置类中已经使用注释详细解释了每个方法的作用了。到此已经配置好
Swagger
了。现在可以测试一下 配置有没有生效,启动项目,在浏览器中输入 http://localhost:8080/test/swagger-ui/
,即可看到
swagger
的 接口页面,说明 Swagger
集成成功。
对照
Swagger
配置文件中的配置,可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握 Swagger 中的配置了,也可以看出,其实
Swagger
配置很简单。
有可能在配置
Swagger
时关不掉,是因为浏览器缓存引起的,清空一下浏览器缓存即可解决问题。
相关配置
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
4. Swagger 的使用
已经配置好了
Swagger
,并且也启动测试了一下,功能正常,下面可以开始使用
Swagger
,重点要掌握
Swagger 中常用的注解,分别在实体类上、Controller
类上以及
Controller
中的方法上,最后查看
Swagger
如何在页面 上呈现在线接口文档的,并且结合 Controller
中的方法在接口中测试一下数据。
4.1 实体类注解
定义
User
实体类,这里主要介绍
Swagger
中的
@ApiModel
和
@ApiModelProperty
注解。
@ApiModel(value = "用户实体类")
public class User {
@ApiModelProperty(value = "用户唯一标识")
private Long id;
@ApiModelProperty(value = "用户姓名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
// 省略 set 和 get 方法
}
其中
@ApiModel
注解用于实体类,表示对类进行说明,用于参数用实体类接收。
@ApiModelProperty
注解用于类中属性,表示对
model
属性的说明或者数据操作更改。
4.2 Controller 类中相关注解
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息")
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "张三", "123456");
return new JsonResult(user);
}
}
1
、
@Api
注解用于类上,表示标识这个类是
swagger
的资源。
2
、
@ApiOperation
注解用于方法,表示一个
http
请求的操作。
3
、
@ApiParam
注解用于参数上,用来标明参数信息。
在浏览器中可以看出
Swagger
页面对该接口的信息展示的非常全面,每个注解的作用以及展示的地方注意对应位置,通过页面即可知道该接口的所有信息,那么直接在线测试一下该接口返回的信息,输入 id
为
1
,看一下返回数据。
可以看出,直接在页面返回了
json
格式的数据,开发人员可以直接使用该在线接口来测试数据的正确与否,非常方便。
@PostMapping("/insert")
@ApiOperation(value = "添加用户信息")
public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
// 处理添加逻辑
return new JsonResult<>();
}
重启项目,然后在浏览器中输入
localhost:8080/swagger-ui.html
看效果
2.Spring Boot 集成 Thymeleaf 模板引擎
1. Thymeleaf 介绍
Thymeleaf
是适用于
Web
和独立环境的现代服务器端
Java
模板引擎。
Thymeleaf
的主要目标是为开发工作流程带来优雅的自然模板,既可以在浏览器中正确显示的
HTML
,也可以用作静态原型,从而在开发团队中实现更强大的协作。
传统的
JSP+JSTL
组合是已经过去了,
Thymeleaf
是现代服务端的模板引擎,与传统的
JSP
不同,
Thymeleaf可以使用浏览器直接打开,因为可以忽略掉拓展属性,相当于打开原生页面,给前端人员也带来一定的便利。
在本地环境或者有网络的环境下,
Thymeleaf
均可运行。由于
thymeleaf
支持
html
原型,也支持在
html标签里增加额外的属性来达到【模板+
数据】的展示方式,所以美工可以直接在浏览器中查看页面效果,当服务启动后,也可以让后台开发人员查看带数据的动态页面效果。
<div class="ui right aligned basic segment">
<div class="ui orange basic label" th:text="${blog.flag}">静态原创信息</div>
</div>
<h2 class="ui center aligned header" th:text="${blog.title}">这是静态标题</h2>
类似于这样,在静态页面时会展示静态信息,当服务启动后,动态获取数据库中的数据后,就可以展示动态数据,th:text
标签是用来动态替换文本的。该例子说明浏览器解释
html
时会忽略
html
中未定义的标签属性,比如 th:text
,所以
thymeleaf
的模板可以静态地运行;当有数据返回到页面时,
Thymeleaf
标签会动态地替换掉静态内容,使页面动态显示数据。
2. 依赖导入
在
Spring Boot
中使用
thymeleaf
模板需要引入依赖,可以在创建项目工程时勾选
Thymeleaf
,也可以创建之后再手动导入
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
另外在
html
页面上如果要使用
thymeleaf
模板,需要在页面标签中引入
th
命名空间
<html xmlns:th="http://www.thymeleaf.org">
3. Thymeleaf 相关配置
因为
Thymeleaf
中已经有默认的配置了,不需要再对其做过多的配置,需要注意一下,
Thymeleaf 默认是开启页面缓存的,所以在开发的时候,需要关闭这个页面缓存
spring:
thymeleaf:
cache: false #
关闭缓存
否则会有缓存,导致页面没法及时看到更新后的效果。比如修改了一个文件,已经
update
到
tomcat
了,但刷新页面还是之前的页面,就是因为缓存引起的。
4. Thymeleaf 的使用
4.1 访问静态页面
这个实际上和
Thymeleaf
没有什么关系,应该说是通用的,把它一并写到这里的原因是一般做网站时,都会做一个 404
页面和
500
页面,为了出错时给用户一个友好的展示,而不至于一堆异常信息抛出来。
Spring Boot中会自动识别模板目录 templates/
下的
404.html
和
500.html
文件。在
templates/
目录下新建一个
error
文件夹,专门放置错误的 html
页面,然后分别打印些信息。例如
404.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>这是 404 页面</body>
</html>
再写一个
controller
来测试一下
404
和
500
页面:
@Controller
@RequestMapping("/thymeleaf")
public class ThymeleafController {
@RequestMapping("/test404")
public String test404() {
return "index";
}
@RequestMapping("/test500")
public String test500() {
int i = 1 / 0;
return "index";
}
}
当在浏览器中输入
localhost:8080/thymeleaf/test400
时,故意输入错误,找不到对应的方法,就会跳转到 404.html 显示。
当在浏览器中输入
localhost:8088/thymeleaf/test505
时,会抛出异常,然后会自动跳转到
500.html
显示。
【注】这里有个问题需要注意一下,在微服务应用开发中会走向前后端分离,在
Controlle
层上都是使用的@RestController 注解,自动会把返回的数据转成
json
格式。但是在使用模板引擎时,
Controller 层就不能用@RestController
注解了,因为在使用
thymeleaf
模板时,返回的是视图文件名,比如上面的
Controller 中是返回到
index.html
页面,如果使用
@RestController
的话,会把
index
当作
String 解析了,直接返回到页面了,而不是去找
index.html
页面,所以在使用模板时要用
@Controller
注解。
4.2 Thymeleaf 中处理对象
thymeleaf 模板中应该如何处理对象信息呢?假如在做个人博客的时候,需要给前端传博主相关信息来展示,那么会封装成一个博主对象,比如:
public class Blogger {
private Long id;
private String name;
private String pass;
// 省去 set 和 get
}
然后在
controller
层中初始化一下:
@GetMapping("/getBlogger")
public String getBlogger(Model model) {
Blogger blogger = new Blogger(1L, "闫峻", "123456");
model.addAttribute("blogger", blogger);
return "blogger";
}
先初始化一个
Blogger
对象,然后将该对象放到
Model
中,然后返回到
blogger.html 页面去渲染。接下来再写一个
blogger.html
来渲染
blogger
信息:
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<html lang="en">
<head>
<meta charset="UTF-8">
<title>博主信息</title>
</head>
<body>
<form action="" th:object="${blogger}" >
用户编号:<input name="id" th:value="${blogger.id}"/><br>
用户姓名:<input type="text" name="username" th:value="${blogger.getName()}" /><br>
登陆密码:<input type="text" name="password" th:value="*{pass}" />
</form>
</body>
</html>
可以看出,在
thymeleaf
模板中,使用
th:object="${}"
来获取对象信息,然后在表单里面可以有三种方式来获
取对象属性。
1
、使用
th:value="*{
属性名
}"
2
、使用
th:value="${
对象
.
属性名
}"
,对象指的是上面使用
th:object
获取的对象
3
、使用
th:value="${
对象
.get
方法
}"
,对象指的是上面使用
th:object
获取的对象
可 以 看 出 , 在
Thymeleaf
中 可 以 像 写
java
一 样 写 代 码 , 很 方 便 。 在 浏 览 器 中 输 入
localhost:8080/thymeleaf/getBlogger
来测试一下数据:
4.3 Thymeleaf 中处理 List
处理
List
和处理对象差不多,但是需要在
thymeleaf
中进行遍历。先在
Controller
中模拟一个
List
。
@GetMapping("/getList")
public String getList(Model model) {
Blogger blogger1 = new Blogger(1L, "张三", "123456");
Blogger blogger2 = new Blogger(2L, "李四", "123456");
List<Blogger> list = new ArrayList<>();
list.add(blogger1);
list.add(blogger2);
model.addAttribute("list", list);
return "list";
}
接下来写一个
list.html
来获取该
list
信息,然后在
list.html
中遍历这个
list
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<html lang="en">
<head>
<meta charset="UTF-8">
<title>博主信息</title>
</head>
<body>
<form action="" th:each="blogger : ${list}" >
用户编号:<input name="id" th:value="${blogger.id}"/><br>
用户姓名:<input type="text" name="password" th:value="${blogger.name}"/><br>
登录密码:<input type="text" name="username" th:value="${blogger.getPass()}"/>
</form>
</body>
</html>
可以看出,其实和处理单个对象信息差不多,
Thymeleaf
使用
th:each
进行遍历,
${}
取
model 中传过来的参数,然后自定义 list 中取出来的每个对象,这里定义为 blogger。表单里面可以直接使用${对象.属性名}来获取list 中对象的属性值,也可以使用${对象.get 方法}来获取,这点和处理对象信息是一样的,但是不能使用*{属性名}来获取对象中的属性,thymeleaf 模板获取不到。
4.4 其他常用 thymeleaf 操作
thymeleaf
中的一些常用的标签操作
![](https://i-blog.csdnimg.cn/blog_migrate/e4c08210742b7a9a2dd59b2d3bde2663.png)
Thymeleaf
还 有 很 多 其 他 用 法 , 这 里 就 不 总 结 了 , 具 体 的 可 以 参 考
Thymeleaf 的 官 方 文 档 https://www.thymeleaf.org/doc/tutorials/3.0/usingthymeleaf.html
。主要要学会如何在
Spring Boot 中去使用 thymeleaf
,遇到对应的标签或者方法,查阅官方文档即可。