Spring Boot笔记总结3

一、Spring Boot 集成 Swagger 在线接口文档

1.Swagger 简介   

解决的问题随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

2.Swagger 官方

打开 Swagger 官网为 https://swagger.io/ 主要掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档。

1. 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

1. Swagger 的使用

已经配置好了 Swagger，并且也启动测试了一下，功能正常，下面可以开始使用 Swagger，重点要掌握 Swagger 中常用的注解，分别在实体类上、Controller 类上以及 Controller 中的方法上，最后查看 Swagger 如何在页面上呈现在线接口文档的，并且结合 Controller 中的方法在接口中测试一下数据。

4. 实体类注解

定义 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 属性的说明或者数据操作更改。

5.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 看效果

6. 总结

主要详细分析 Swagger 的优点以及 Spring Boot 集成 Swagger，包括配置，涉及到了实体类和接口类以及如何使用。最后通过页面测试，可以体验 Swagger 的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。

二、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 中的一些常用的标签操作

标签	功能	例子
th:value	给属性赋值	<input th:value="${blog.name}" />
th:style	设置样式	th:style="'display:'+@{(${sitrue}?'none':'inline-block')} + ''"
th:onclick	点击事件	th:οnclick="'getInfo()'"
th:if	条件判断	<a th:if="${userId == collect.userId}" >
th:href	超链接	<a th:href="@{/blogger/login}">Login</a>
th:unless	条件判断和 th:if 相反	<a th:href="@{/blogger/login}"   th:unless=${session.user null}>Login</a>	!=
th:switch	配合 th:case	div th:switch="${user.role}">
th:case	配合 th:switch	<p th:case="'admin'">administator</p>
th:src	地址引入	<img alt="csdn logo" th:src="@{/img/logo.png}" />
th:action	表单提交的地址	<form th:action="@{/blogger/update}">

Thymeleaf 还有很多其他用法，这里就不总结了，具体的可以参考 Thymeleaf 的官方文档 https://www.thymeleaf.org/doc/tutorials/3.0/usingthymeleaf.html。主要要学会如何在 Spring Boot 中去使用 thymeleaf，遇到对应的标签或者方法，查阅官方文档即可。

5. 总结

Thymeleaf 在 Spring Boot 中使用非常广泛，主要分析 thymeleaf 的优点，以及如何在 Spring Boot 中集成并使用 thymeleaf 模板，包括依赖、配置，相关数据的获取、以及一些注意事项等。最后列举了一些 thymeleaf 中常用的标签，在实际项目中多使用，多查阅就能熟练掌握，thymeleaf 中的一些标签或者方法不用死记硬背，用到什么去查阅什么，关键是要会在 Spring Boot 中集成，用的多了就熟能生巧。