SpringBoot集成Swagger及Thymeleaf

一、Swagger简介

   1.1  面对的问题

我去网上查了一些资料 ，发现了现在的网站结构基本都由原来的后端而来，变成了前后端分离的样子。前端和后端只有一个联系就是：变成了 API 接口，所以 API 文档变成了前后端联系的关键问题所在，变得特别重要，要重视到这个问题！！！！

我认为有一个问题在于随着代码的持续更新状态，在开发新的接口或者更新旧的接口后，我感觉这个开发任务太繁重了，写的每一个文档很难持续跟着更新，Swagger 就是用来解决这个问题非常重要的工具了。

使用接口的话就是，开发人员是不需要提供文档得，一个 Swagger 地址，可展示在线的 API 接口文档，除了这个之外，我还了解到调用接口的人员还可以在线测试接口数据，开发人员在开发接口时，也可以利用 Swagger 在线接口文档测试接口数据，这样是非常方便也比较通俗易懂！

 1.2   Swagger

 Swagger的官网：https://swagger.io/

最主要就是学习Spring Boot 中如何导入 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>

三、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.xu.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("xumiaomiao", "http://baidu.com", "xu@xu.com")) 设置联系方式
.version("1.0") 设置版本
.build(); 构建
}

在这个配置类中我已经使用详细的注释的解释了每个方法的作用了。到目前为止已经配置好 Swagger 了。现在我来测试一下 配置有没有生效，启动项目，在浏览器中输入 http://localhost:8080/test/swagger-ui/ ，即可以容易的看到 swagger 的 接口页面，说明 Swagger 集成成功，大功告成啦！

现在我就可以对比一下Swagger 配置文件中的配置，已经很明确的知道配置类中每个方法的作用。这样我就很容易理解和掌握 Swagger 中的配置了。

其实 Swagger 配置很简单。 有可能在配置 Swagger 时关不掉，是因为浏览器缓存引起的，清空一下浏览器缓存问题就可以解决了。

四、运用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<>();
}

五、Thymeleaf 模板引擎

5.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 标签会动态地替换掉静态内容文本，使页面动态显示出我要的数据。

5.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">

5.3 Thymeleaf 相关配置

因为 Thymeleaf 中已经有默认的配置了，不需要再对它做过多的配置，但是需要注意一下， Thymeleaf 默认是开启页面缓存的，所以在开发的时候，需要关闭这个页面缓存。

否则会有缓存，导致页面没法及时看到更新后的效果。假如修改了一个文件，已经 更新 到 tomcat 了，但刷新页面，又回到之前的页面就是因为缓存引起的问题，切记！！！

5.4 Thymeleaf 的使用

 5.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 显示。

 5.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 页面去渲染。接下来再写：

<!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>

 5.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, "徐苗苗2", "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>

 5.4.4  常用 thymeleaf 操作

下面是thymeleaf 中的一些常用的标签操作：