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代码。

内容摘要:基于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无法自动生成文档,目前主流的解决办法,基本是人工编写、或者框架工具生成。
menu_saveimg_savepath20190213141823

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
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接口详细的参数,请求和返回消息的例子。
swagger_ui

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的目录都可以配置:
SpringBoot_RestDocs_

要编写对应的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。Spring_Rest_Docs_

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技术进阶群
进群方式:钉钉扫码入群
C926B5D9_9BC2_4452_B14E_7F2F506EDAF9
阿里巴巴MongoDB群
_MongoDB_185

目录
相关文章
|
8天前
|
缓存 前端开发 API
API接口封装系列
API(Application Programming Interface)接口封装是将系统内部的功能封装成可复用的程序接口并向外部提供,以便其他系统调用和使用这些功能,通过这种方式实现系统之间的通信和协作。下面将介绍API接口封装的一些关键步骤和注意事项。
|
15天前
|
监控 前端开发 JavaScript
实战篇:商品API接口在跨平台销售中的有效运用与案例解析
随着电子商务的蓬勃发展,企业为了扩大市场覆盖面,经常需要在多个在线平台上展示和销售产品。然而,手工管理多个平台的库存、价格、商品描述等信息既耗时又容易出错。商品API接口在这一背景下显得尤为重要,它能够帮助企业在不同的销售平台之间实现商品信息的高效同步和管理。本文将通过具体的淘宝API接口使用案例,展示如何在跨平台销售中有效利用商品API接口,以及如何通过代码实现数据的统一管理。
|
20天前
|
Java 应用服务中间件 Maven
SpringBoot 项目瘦身指南
SpringBoot 项目瘦身指南
37 0
|
26天前
|
Java
【Java】一个简单的接口例子(帮助理解接口+多态)
【Java】一个简单的接口例子(帮助理解接口+多态)
16 0
|
11天前
|
设计模式 安全 Java
Java并发编程实战:使用synchronized关键字实现线程安全
【4月更文挑战第6天】Java中的`synchronized`关键字用于处理多线程并发,确保共享资源的线程安全。它可以修饰方法或代码块,实现互斥访问。当用于方法时,锁定对象实例或类对象;用于代码块时,锁定指定对象。过度使用可能导致性能问题,应注意避免锁持有时间过长、死锁,并考虑使用`java.util.concurrent`包中的高级工具。正确理解和使用`synchronized`是编写线程安全程序的关键。
|
1天前
|
设计模式 Java
Java接口与抽象类
Java接口与抽象类
6 0
|
1天前
|
XML Java C++
【Spring系列】Sping VS Sping Boot区别与联系
【4月更文挑战第2天】Spring系列第一课:Spring Boot 能力介绍及简单实践
19 0
【Spring系列】Sping VS Sping Boot区别与联系
|
2天前
|
人工智能 API 开发者
免费使用Kimi的API接口,kimi-free-api真香
今年AI应用兴起,各类智能体涌现,但API免费额度有限。为解决这一问题,GitHub上的[kimi-free-api](https://github.com/LLM-Red-Team/kimi-free-api)项目提供了方便,支持高速流式输出、多轮对话等,与ChatGPT接口兼容。此外,还有其他大模型的免费API转换项目,如跃问StepChat、阿里通义Qwen等。该项目可帮助用户免费体验,通过Docker-compose轻松部署。只需获取refresh_token,即可开始使用。这个开源项目促进了AI学习和开发,为探索AI潜力提供了新途径。
127 2
|
5天前
|
安全 Java 编译器
接口之美,内部之妙:深入解析Java的接口与内部类
接口之美,内部之妙:深入解析Java的接口与内部类
25 0
接口之美,内部之妙:深入解析Java的接口与内部类
|
7天前
|
JSON 监控 API
在API接口对接中关键示例问题(1)
在API接口对接中,有几个关键的问题需要注意,以确保接口的稳定性、安全性和易用性。以下是这些问题及部分示例代码的简要概述