8. Spring Boot 2.5 实战 API 帮助文档 Swagger

Spring Boot 2.5 实战 API 帮助文档Swagger

内容简介：
一、REST API 帮助文档
二、REST API 自动生成帮助文档 Swagger

一、REST API 帮助文档

目前大型移动互联网平台，像淘宝、微信，抖音、拼多多，包括滴滴打车、美团等，
都是前后端分离的架构，我们叫微服务架构。
Swagger 是自动化 API 文档的生成工具，这个工具之前是 Spring Boot 项目来进
行集成，现在使用 Spring Boot 项目做后端开发，写 API 的代码的机会比较多，咱们把
这个工具给大家介绍一下。
作为一个快速开发框架，是 Spring Boot 提供了自己的一套 API 的文档工具，目前
来看，Swagger 使用比较多，这几年来普及率非常高，因为它非常方便，它的文档生成
基本上都是自动化，只需要加一个简单的处理就可以。

对于后端开发来说，不需要自己专门写一套 word 文档，发给前端，前端再自己去
测试，再调进来后台 API。Swagger 文档部署完以后，前端可以直接拿到，然后进行在
线调试，非常方便。简化前后端协助，协助避免出错。

二、REST API 自动生成帮助文档 Swagger

1. Swagger 自动化文档工具

1）Swagger 是一个完整的 API 生态，工具，规范，代码生成。
2）用于描述，生成，使用和可视化 RESTful Web 服务。
3）Swagger API project 2011 Tony Tam 创立 最早 Java 版。
4）SmartBear Software 公司支持，Apache License 2.0。
5）OpenAPI Spec。
6）Swagger and OAS。
7）Swagger 2 to OpenAPI 3。
8）捐赠给 linux 基金会。
9）行业标准规范。
10）Swagger Tools 一套工具：设计、开发、测试、监控、治理。

2. Spring REST Docs

Spring REST Docs
1）Spring REST Docs 帮助自动化生成 RESTful 服务的文档。
2）使用 Asciidoctor 编写的手写文档。
3）Spring REST Docs 为 RESTful 服务生成准确且可读的文档。
4）将手写文档与使用 Spring 测试生成的文档片段相结合。
5）不受 Swagger 等工具生成的文档的限制。
6）它可以生成准确，简洁和结构良好的 API 文档。
7）Spring REST Docs 支持测试驱动 Test Driven。
8）pring REST Docs 支持 Spring MVC Test 框架，Spring WebFlux 的 WebTest
Client 或 REST Assured 3 测试驱动。
9）Spring Boot 提供了注解@AutoConfigureRestDocs。
10）替代 SpringFox Swagger。

3. 优点

1）手写文档与使用 Spring Test 框架生成的文档片段结合。
2）curl and http request snippets are generated。
3）easy to package documentation in projects jar file。
4）easy to add extra information to the snippets。
5）supports both JSON and XML。

4. MockMvc

1）MockMvc 是 Spring MVC Test 工具类，支持 Assert 和 Chain。
2）@Mock 创建模拟对象，Mock。
3）@InjectMocks 会自动将 mock 依赖注入测试对象。
4）MockitoAnnotations.initMocks（this）初始化。
5）MockMvcBuilders.standaloneSetup（…）.build（）通过注册一个或多个
@Controller 实例并以编程方式配置 Spring MVC 基础结构来构建 MockMvc 实例。
6）@Test 标注测试方法。
7）@WebMvcTest 注解用于 Spring MVC 测试。 它禁用完全自动配置，而只应用
与 MVC 测试相关的配置。
8）WebMvcTest 注解也自动配置 MockMvc 实例。

5. Asciidoctor 插件步骤

1）pom.xml 添加 Asciidoctor 插件
2）添加对 spring-restdocs-mockmvc 的依赖
3）配置属性 asciidocs 输出位置 sourceDirectory
4）配置测试任务 task 输出位置 outputDirectory
5）配置 asciidoctor task
6）snippets 定义 snippets 输出位置
7）使 task 依赖于 test 任务，以便在创建文档之前运行测试
8）将 snippets 配置为输入。将在此目录下创建所有代码段

6. REST Assured

1）Rest-Assured 由 Java 实现的 REST API 测试框架。
2）在 Java 中测试和验证 REST 服务比在 Ruby 和 Groovy 等动态语言中更难。
3）REST Assured 简化 REST API 测试。
4）专为测试 REST API 而设计的 DSL。
5）Java DSL，用于轻松测试 REST 服务。
6）REST Assured 支持任何 HTTP 方法，但明确支持 POST，GET，PUT，DELETE，
OPTIONS，PATCH 和 HEAD，并包括指定和验证例如 parameters, headers, cookies
body 。
7）自动化测试
8）http://rest-assured.io/

7. Spring Auto Rest Docs

Spring REST Docs 最低要求
1）Java 8
2）Spring Framework 5 (5.0.2 or later)
3）此外, the spring-restdocs-restassured 要求 :
4）REST Assured 3.0

8. Spring Rest Docs Demo

Spring Rest Docs 实战

9. Asciidocs Maven Plugins

Spring REST Docs可以在线方便的调试自己的API，但是没有 Swagger 使用方便，
这边就简单介绍下，重点还是讲实战 Swagger。

10. Spring Boot 2.0 实战 Swagger

引用 Swagger 的包，需要自己做一些参数化的配置，简单的可以在配置文件进行，
复杂一些配置需要在代码里面进行。生成的调试方式也比较简单，生成的网页里面在详
细的检索描述性，可以在线的发送 get、Post 等经典请求格式，很方便的去调接口，对
于前后端分离的架构来说是很方便。

页面打开两种方式：

http://localhost:8081/swagger-ui.html
1）/v2/api-docs
2）Swagger UI /swagger-ui.html
接口文档的版本可以不断的变化，也可以在后台进行配置。

11. Swagger-core 注解

在开发过程中，默认的话什么都不加的话，实际解析的信息如说控制器或者类别的
基本信息。如果希望对内加一些描述信息。对原接口加原表述信息的话，可以加进来如
传输的数据类型，加个 model 的 API model 加个说明，模组里面字段你可以加
property 这个说明。操作具体方法的话可以 operation，参数的话有 pyramid 的说明，
应答消息和请求消息的话也可以加 response，这种相对的这些注解说明都可以了。它会
自动的把这些信息提取出来，生成放到 Swagger 在线帮助文档里。

12. Spring Boot 2.0 Rest API 注解

应答消息 401、404、403 等消息可以自己定制，如整合 API 的类型的话，可以加入
淘宝用户的 API 接口等，根据自己的需求进行添加。

接口也可以分类，目前是这里简单做了几个分类：订单接口，用户接口，并可以在
里面进行测试，方便在线检查，并视图形式，反馈各个消息类型的结果。
测试有错注意点：
 需要使用 RestController，不要是用 Controller。
 出现 order repository 问题，是没有数据的原因。
 Swagger 功能非常强大，也方便调试开发，尤其是前后端分离的架构。下节课继续

里面进行测试，方便在线检查，并视图形式，反馈各个消息类型的结果。
测试有错注意点：
 需要使用 RestController，不要是用 Controller。
 出现 order repository 问题，是没有数据的原因。
 Swagger 功能非常强大，也方便调试开发，尤其是前后端分离的架构。下节课继续
讲 Spring Boot 的性能监控，内容容器等重要内容。