开发者学堂课程干货总结——Spring Boot 2.5.x开发实战（八）

哈喽各位同学们大家好呀 假期大家休息的怎么样 放假回来上班的第一天小编继续大家分享开发者学院中课程“Spring Boot 2.5实战API帮助文档Swagger”干货总结哦~Spring Boot 2.5.x开发实战可是Java中级工程师必备课程

课程链接以及图谱地址小编已经为大家指路了 搭配学习效果更佳

课程名称 Spring Boot 2.5.x开发实战

课程地址 https://developer.aliyun.com/learning/course/71?spm a2c6h.21254954.0.0.4e905907uoWZzr

图谱名称 Alibaba Java 技术图谱

图谱地址 https://developer.aliyun.com/graph/java?spm a2c6h.21110250.J_5703890090.6.700e3c67EjOBeJ

Spring Boot 2.5实战API帮助文档Swagger

一、REST?API帮助文档?

目前大型移动互联网平台 像淘宝、微信 抖音、拼多多 包括滴滴打车、美团等 都是前后端分离的架构 我们叫微服务架构。?

?Swagger是自动化API文档的生成工具 这个工具之前是Spring Boot项目来进行集成 现在使用Spring?Boot项目做后端开发 写API的代码的机会比较多 咱们把这个工具给大家介绍一下。?

作为一个快速开发框架 是Spring Boot提供了自己的一套API的文档工具 目前来看 Swagger使用比较多 这几年来普及率非常高 因为它非常方便 它的文档生成基本上都是自动化 只需要加一个简单的处理就可以。?

?

?

?

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

?

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

?

官网?https://swagger.io?

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一套工具 设计、开发、测试、监控、治理。?

?

?

?

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. Spring REST?Docs支持Spring?MVC?Test框架 Spring?WebFlux的???WebTestClient或REST?Assured 3测试驱动。?

9. Spring Boot?提供了注解 AutoConfigureRestDocs?

10.?替代SpringFox?Swagger?

?

优点?

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。?

?

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实例。?

?

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配置为输入。将在此目录下创建所有代码段?

?

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/?

?

?

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?

?

?

Spring Rest Docs?Demo?

Spring Rest?Docs实战?

?

?

Asciidocs?Maven Plugins?

?

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

?

Spring Boot 2.0?实战Swagger?

?

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

?

页面打开两种方式 ?

http://localhost:8081/swagger-ui.html?

1. /v2/api-docs??

2. Swagger UI /swagger-ui.html?

?

接口文档的版本可以不断的变化 也可以在后台进行配置?

?

Swagger-core?注解?

?

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

?

Spring Boot 2.0 Rest?API注解?

?

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

?

?

?

接口也可以分类 目前是这里简单做了几个分类 订单接口 用户接口 并可以在里面进行测试 方便在线检查 并视图形式 反馈各个消息类型的结果。?

测试有错注意点 ?

需要使用RestController 不要是用Controller?

出现order repository 问题 是没有数据的原因?

Swagger功能非常强大 也方便调试开发 尤其是前后端分离的架构。下节课继续讲Spring?Boot的性能监控 内容容器等重要内容。?

本文转自网络，原文链接：https://developer.aliyun.com/article/784707
本站部分内容转载于网络，版权归原作者所有，转载之目的在于传播更多优秀技术内容，如有侵权请联系QQ/微信：153890879删除，谢谢！