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

目录
相关文章
|
2月前
|
前端开发 Java 关系型数据库
基于Java+Springboot+Vue开发的鲜花商城管理系统源码+运行
基于Java+Springboot+Vue开发的鲜花商城管理系统(前后端分离),这是一项为大学生课程设计作业而开发的项目。该系统旨在帮助大学生学习并掌握Java编程技能,同时锻炼他们的项目设计与开发能力。通过学习基于Java的鲜花商城管理系统项目,大学生可以在实践中学习和提升自己的能力,为以后的职业发展打下坚实基础。技术学习共同进步
239 7
|
3月前
|
JSON Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
111 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
3月前
|
缓存 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
128 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
|
3月前
|
Java Maven 微服务
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的 maven 依赖
在项目中使用Swagger2工具时,需导入Maven依赖。尽管官方最高版本为2.8.0,但其展示效果不够理想且稳定性欠佳。实际开发中常用2.2.2版本,因其稳定且界面友好。以下是围绕2.2.2版本的Maven依赖配置,包括`springfox-swagger2`和`springfox-swagger-ui`两个模块。
77 0
|
3月前
|
前端开发 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档—— Swagger 简介
第6课介绍了在Spring Boot中集成Swagger2以展示在线接口文档的方法。随着前后端分离架构的发展,API文档成为连接前端与后端开发的重要纽带。然而,代码更新频繁导致文档难以同步维护,Swagger2解决了这一问题。通过Swagger,在线API文档不仅方便了接口调用方查看和测试,还支持开发者实时测试接口数据。本文使用Swagger 2.2.2版本,讲解如何在Spring Boot项目中导入并配置Swagger2工具,从而高效管理接口文档。
134 0
|
2月前
|
前端开发 Java 物联网
智慧班牌源码,采用Java + Spring Boot后端框架,搭配Vue2前端技术,支持SaaS云部署
智慧班牌系统是一款基于信息化与物联网技术的校园管理工具,集成电子屏显示、人脸识别及数据交互功能,实现班级信息展示、智能考勤与家校互通。系统采用Java + Spring Boot后端框架,搭配Vue2前端技术,支持SaaS云部署与私有化定制。核心功能涵盖信息发布、考勤管理、教务处理及数据分析,助力校园文化建设与教学优化。其综合性和可扩展性有效打破数据孤岛,提升交互体验并降低管理成本,适用于日常教学、考试管理和应急场景,为智慧校园建设提供全面解决方案。
277 70
|
18天前
|
SQL Java 数据库
解决Java Spring Boot应用中MyBatis-Plus查询问题的策略。
保持技能更新是侦探的重要素质。定期回顾最佳实践和新技术。比如,定期查看MyBatis-Plus的更新和社区的最佳做法,这样才能不断提升查询效率和性能。
62 1
|
1月前
|
安全 Java API
Spring Boot 功能模块全解析:构建现代Java应用的技术图谱
Spring Boot不是一个单一的工具,而是一个由众多功能模块组成的生态系统。这些模块可以根据应用需求灵活组合,构建从简单的REST API到复杂的微服务系统,再到现代的AI驱动应用。
270 8
|
2月前
|
XML JSON API
如何从 Swagger 导出 API 文档
Swagger 使这项任务相对简单,允许开发者以各种格式(如 JSON 和 YAML)导出 API 文档。在这篇博文中,我们将详细探讨如何从 Swagger 导出 API 文档。
如何从 Swagger 导出 API 文档
|
3月前
|
前端开发 Cloud Native Java
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
博客不应该只有代码和解决方案,重点应该在于给出解决方案的同时分享思维模式,只有思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现