Java Spring Boot 2.0 API接口实战Swagger和Spring REST Docs帮助文档

内容摘要：基于Java Spring Boot 2.0可以快速开发REST API，但是如何根据API自动生成 Help Docs是非常重要的问题。本次课程详细介绍几种不同的Rest Help Docs的构建方式，Swagger和Rest Docs、OpenAPI核心原理与区别优缺点，并给出Demo代码。
1、API开发、微服务帮助文档解决方法

企业应用接口，目前主要是REST API为主，针对前后端分离架构，或者移动多层架构开发，基于HTTP+JSON方式最为常见。但是API的接口文档一直是个比较棘手的问题，非常重要，几乎每个API开发者都会涉及到接口API文档的编写问题。为接口的调用者提供详细的API文档，成为非常重要的工作内容。

早期Web服务开发者可以使用WSDL，但是REST API无法自动生成文档，目前主流的解决办法，基本是人工编写、或者框架工具生成。

2、Swagger 强大的文档工具生态
Java开源的工具生态太强大，Swagger就是其中一个非常经典的工具。为了解决API接口文档的生产问题，国外的技术专家开始编写一些帮助工具插件，其中以Swagger最为有名。开源代码地址：https://github.com/swagger-api/swagger-core
2011年9月开源以后，社区更多的人加入，陆续贡献了验证、测试、UI、规范等新的组件模块。最后有人仿制了其他语言的版本。比如Node、Ruby、C#等版本。

现在Swagger几乎成为API开发必须的工具框架，最早是Tony Tam为公司内部Java项目编写的工具类，生成帮助文档，现在已经是一个完整的API生态，工具，规范，代码生成；包括可视化管理界面。
用于描述，生成，使用和可视化RESTful Web服务；
https://swagger.io/。

Swagger API project 2011 Tony Tam创立 最早Java版；
SmartBear Software公司支持，Apache License 2.0；
早期的Swagger API规范，更名为OpenAPI Spec；成为标准。
Swagger and OAS紧密结合；
Swagger 2 to OpenAPI 3；
现在Swagger 捐赠给linux基金会，；
因为诞生比较早，加上多语言的支持，事实上已经成为行业标准规范；
Swagger 3.0版本改名为OpenAPI 有专门的委员会参与制定规范。
Swagger Tools有提供强大的API工具，包括：设计、开发、测试、监控、治理等领域，十分的强大。

3、Spring Rest Docs 新特性
Spring REST Docs的目标替代SpringFox Swagger，帮助自动化生成RESTful服务的文档。
使用Asciidoctor编写的手写文档；
Spring REST Docs为RESTful服务生成准确且可读的文档。
将手写文档与使用Spring测试生成的文档片段相结合。
不受Swagger等工具生成的文档的限制。
它可以生成准确，简洁和结构良好的API文档。
Spring REST Docs支持测试驱动Test Driven。
Spring REST Docs支持Spring MVC Test框架，Spring WebFlux的WebTestClient或REST Assured 3测试驱动。
Spring Boot 提供了注解@AutoConfigureRestDocs简化文档开发。
但是目前来看，取代Swagger比较难，因为Swagger本身生态系统太强大，而且已经进化成行业标准规范了。Spring Rest Docs 也有人提供扩展的对OpenAPI的支持。
4、Spring Boot 2.0 实战 Swagger2 Demo
首先新建Java Spring Boot 2.0项目，然后加入对应的Swagger依赖，使用2.0版本就可以了。

<!-- Swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.8.0</version>
        </dependency>

API接口使用Swagger注解方式配置，比较方便，提供了。模拟淘宝淘宝订单 API接口OrderController。而且Swagger提供了注解@Api、@ApiModel、@ApiRequest、@ApiResponse等方便进行API开发与设计。

@RestController
@RequestMapping("/api/v1/orders")
@Api(value = " 淘宝订单 API接口, taobao Order REST API", description = "淘宝订单 API接口，api of  orders in TaoBao  System")
public class OrderController {
    @Autowired
    private OrderRepository orderRepository;

    @ApiOperation(value = "查询所有订单,get a list of all orders", response = List.class)
    @ApiResponses(value = { @ApiResponse(code = 200, message = "Successfully retrieved list"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found") })
    @GetMapping("/getAll")
    public List<Order> getAll() {
        return orderRepository.getAll();
    }

    @ApiOperation(value = "查询单个订单，Get an Order by Id")
    @GetMapping("/getById/{id}")
    public ResponseEntity<Order> getById(
            @ApiParam(value = "Order id from which Order object will retrieve", required = true) @PathVariable(value = "id") Long id) {
        Order order = orderRepository.getById(id);

        return ResponseEntity.ok().body(order);
    }

十分方便，最后配置完成，启动项目，在浏览器中输入地址 http://localhost:8080/swagger-ui.html，
可以看到API的帮助文档页面，非常的详细，点击进去可以看到每个API接口详细的参数，请求和返回消息的例子。

5、Spring Boot 2.0 实战 Rest Docs Demo

 Rest Docs的开发相对比较麻烦，除了依赖，还需要严格的编写Test测试代码，保证测试代码通过，在进行文档生成，帮助文档生成可以使用maven实现。pom配置ASCIIdoctor的生成插件。

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.7</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html</backend>
                            <doctype>book</doctype>
                        </configuration>
                    </execution>
                </executions>
                …
</plugin>

项目结构如下，生成文档doc和合并html的目录都可以配置：

要编写对应的Test测试代码，保证测试用例成功。Junit4和5版本还存在差别，5使用的是扩展类.4使用的是注解方式。

@Rule
    public JUnitRestDocumentation jUnitRestDocumentation = new JUnitRestDocumentation();

@SpringBootTest
//创建REST Doc for 5.0

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class OrdersControllerJunit5Test {

    private MockMvc mockMvc;

    @BeforeEach
    public void setUp(WebApplicationContext webApplicationContext,
                      RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders
                .webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    public void getPersonByIdShouldReturnOk() throws Exception {
        this.mockMvc.perform(RestDocumentationRequestBuilders.get("/orders/{id}", 1))
                .andExpect(status().isOk())
                .andExpect(content().contentType("application/json;charset=UTF-8"))
                .andDo(document("orders/getById",
                        pathParameters(parameterWithName("id")
                                .description("订单编号")),
                        responseFields(
                                fieldWithPath("id")
                                        .description("订单编号Unique identifier of the order."),
                                fieldWithPath("title")
                                        .description("订单标题title of the order."),
                                fieldWithPath("desc")
                                        .description("订单描述desc of the order."),
                                fieldWithPath("price")
                                        .description("订单价格price of the order.")
                        )
                ));
    }

}

生成的doc分解为碎片模式，可以提供多个不同的碎片文档，分解为不同的请求、应答、消息体、字段等文档。以订单Order接口为例子：
==== CURL 请求
include::{snippets}/orders/get-by-id/curl-request.adoc[]
==== Path 参数
include::{snippets}/orders/get-by-id/path-parameters.adoc[]
==== Request 请求
include::{snippets}/orders/get-by-id/http-request.adoc[]
==== Response 应答字段
include::{snippets}/orders/get-by-id/response-fields.adoc[]
==== Response消息例子
include::{snippets}/orders/get-by-id/http-response.adoc[]
最后可以选择合并生成统一的html。

6、总结

从开发体验、复杂度来看，Swagger更加的方便，配置相对简单。
从广泛程度来看，Swagger3目前已经成为API标准，OpenAPI。

从编程语言，最早支持Java，现在Node、Ruby、C#等y且得到许多语言的支持。

Swagger API工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。 

支持虽然大多数用户通过Swagger UI工具识别Swagger，
Swagger工具集包括对自动生成文档，代码生成和测试用例支持。
Swagger由SmartBear Software赞助,现在交给Linux基金会以后更加的强大，一直是开源软件的强力支持者，并得到了广泛的采用。
Spring Rest Docs设计目标很好，支持严格的Test Driven测试驱动的开发模式，而且可以编写灵活的Java测试代码，Spring REST Docs支持Spring MVC Test框架，Spring WebFlux的WebTestClient或REST Assured 3测试驱动。
但是开发配置相对繁琐，而且对于测试用例要求必须成功通过，综合对比不如Swagger方式方便，接地气，而且最新的Rest Docs也有扩展支持Open API标准。
7、视频课程
本次课程回顾 https://yq.aliyun.com/articles/684226
视频地址：https://yq.aliyun.com/live/859
PPT地址：https://yq.aliyun.com/live/859

8、阿里巴巴Java群超过2800人
直播地址：Java技术进阶群
进群方式：钉钉扫码入群

阿里巴巴MongoDB群