基于springboot的swagger和thmeleaf

1. swagger在线接口文档

1.1 简介

1.1.1 解决的问题

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

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

1.1.2 swagger官方网址

        swagger的官方网址如下：

https://swagger.io/

2. swagger的maven依赖

使用swagger时需要导入的依赖如下：

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3. 使用swagger时相关配置

@EnableOpenApi
@Configuration
public class Swagger3Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
.enable(true)// 是否关闭在线文档，生产环境关闭
.apiInfo(apiInfo()) // 指定构建 api 文档的详细信息的方法
.select()  
.apis(RequestHandlerSelectors.basePackage("com.yan.action"))// 指定要生成 api 接口的包路径，这里把 action 作为包路径，生成 controller 中的所有接口
.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("qiyu", "http://baidu.com", "qi@qi.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 swagger在实体类上的常用注解

@ApiModel	用于描述实体类，可以添加一些描述信息，如名称、描述、扩展等。
@ApiModelProperty	用于描述实体类的属性，可以添加一些描述信息，如名称、描述、数据类型、是否必填等。
@Api	用于描述API接口，可以添加一些描述信息，如名称、描述、分组等。
@ApiOperation	用于描述API接口的具体操作，可以添加一些描述信息，如名称、描述、请求方法、返回类型等。
@ApiParam	用于描述API接口的参数，可以添加一些描述信息，如名称、描述、数据类型、是否必填等。

4.2 Controller类中的常用注解

@Controller	将一个类标识为Controller组件，用于处理HTTP请求。
@RequestMapping	用于映射路由路径或URL到一个Controller的方法上。
@GetMapping @PostMapping @PutMapping @DeleteMapping	用于映射HTTP GET、POST、PUT、DELETE请求到一个Controller的方法上。
@PathVariable	用于将URI路径上的变量（占位符）绑定到方法的参数上。
@RequestBody	用于将请求体中的数据绑定到方法的参数上。
@RequestParam	用于将请求参数绑定到方法的参数上。
@ResponseBody	用于将方法的返回值直接作为响应体发送给客户端。
@RestController	结合了@Controller和@ResponseBody的功能，用于声明一个Restful风格的Controller。

5. Swagger具有以下几个优点：

        1. 自动生成API文档：Swagger可以通过扫描代码，自动生成可交互的API文档。这样可以方便地查看和了解每个API的用法、参数、返回值等信息，大大减少了编写和维护API文档的工作量。

        2. 提供可视化界面：Swagger UI 提供了一个美观直观的用户界面，开发人员可以通过浏览器直接查看和测试API接口。这对于调试和验证接口的正确性非常有帮助。

        3. 接口测试工具：Swagger集成了一些常用的接口测试功能，例如发送请求、查看请求响应等，可以方便地对API进行测试和调试，提高开发效率。

        4. 接口定义可读性强：Swagger注解提供了强大的接口描述功能，可以对接口、参数、返回值等进行详细的注释说明。这样可以使团队成员更容易理解和使用接口，减少沟通成本。

        5. 支持多种语言和框架：Swagger并不局限于特定的后端语言或框架，可以与多种语言和框架集成使用，如Java、Python、Node.js等。这使得Swagger成为一个广泛使用的API开发工具。

        6. 提供交互式API体验：Swagger UI界面不仅提供了API文档的展示，还具有交互式的功能，如尝试请求、参数自动补全、错误反馈等。这使得开发人员可以更好地理解和使用API接口。

        7. 接口版本管理：Swagger支持在API文档中灵活管理和展示不同版本的接口，方便开发人员追踪和比较不同版本之间的变化。

        8. 社区庞大活跃：Swagger拥有一个庞大的开发者社区，提供了丰富的文档和资源，可以获取大量的示例代码、教程和解决方案，帮助开发人员更好地使用和定制Swagger。

        总的来说，Swagger简化了API文档的创建和维护工作，提供了丰富的功能和工具，使得API的开发和使用变得更加高效和方便。它在API开发过程中起到了明显的提升开发效率、减少沟通成本和改善用户体验的作用。