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

简介: Spring Boot 2.5.x开发实战课时8——Spring Boot 2.5实战API帮助文档Swagger,Spring Boot 2.5.x开发实战是学习Java Spring Cloud微服务架构的必经之路。电子书+视频为同学带来最佳学习效果,文字、课程链接、图谱地址统统为大家放送了哦

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

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

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

课程地址:https://developer.aliyun.com/learning/course/71

图谱名称:Alibaba Java 技术图谱

图谱地址:https://developer.aliyun.com/graph/java


Spring Boot 2.5实战API帮助文档Swagger


一、REST API帮助文档 

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

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

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

 

image.png 

 

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

 

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

image.png 

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

image.png 

 

 

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实战 

image.png 

 

Asciidocs Maven Plugins 

image.pngimage.png 

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

 

Spring Boot 2.0 实战Swagger 

image.png 

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

 

页面打开两种方式: 

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

1. /v2/api-docs  

2. Swagger UI /swagger-ui.html 

 

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

 

Swagger-core 注解image.png 

 

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

 

Spring Boot 2.0 Rest API注解 

image.png 

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

 

image.png 

image.png 

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

测试有错注意点: 

需要使用RestController,不要是用Controller 

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

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

相关文章
|
23天前
|
监控 Java 应用服务中间件
SpringBoot是如何简化Spring开发的,以及SpringBoot的特性以及源码分析
Spring Boot 通过简化配置、自动配置和嵌入式服务器等特性,大大简化了 Spring 应用的开发过程。它通过提供一系列 `starter` 依赖和开箱即用的默认配置,使开发者能够更专注于业务逻辑而非繁琐的配置。Spring Boot 的自动配置机制和强大的 Actuator 功能进一步提升了开发效率和应用的可维护性。通过对其源码的分析,可以更深入地理解其内部工作机制,从而更好地利用其特性进行开发。
42 6
|
29天前
|
XML Java 应用服务中间件
Spring Boot 两种部署到服务器的方式
本文介绍了Spring Boot项目的两种部署方式:jar包和war包。Jar包方式使用内置Tomcat,只需配置JDK 1.8及以上环境,通过`nohup java -jar`命令后台运行,并开放服务器端口即可访问。War包则需将项目打包后放入外部Tomcat的webapps目录,修改启动类继承`SpringBootServletInitializer`并调整pom.xml中的打包类型为war,最后启动Tomcat访问应用。两者各有优劣,jar包更简单便捷,而war包适合传统部署场景。需要注意的是,war包部署时,内置Tomcat的端口配置不会生效。
233 17
Spring Boot 两种部署到服务器的方式
|
1月前
|
人工智能 Java API
阿里云工程师跟通义灵码结伴编程, 用Spring AI Alibaba来开发 AI 答疑助手
本次分享的主题是阿里云工程师跟通义灵码结伴编程, 用Spring AI Alibaba来开发 AI 答疑助手,由阿里云两位工程师分享。
阿里云工程师跟通义灵码结伴编程, 用Spring AI Alibaba来开发 AI 答疑助手
|
1月前
|
监控 JavaScript 数据可视化
建筑施工一体化信息管理平台源码,支持微服务架构,采用Java、Spring Cloud、Vue等技术开发。
智慧工地云平台是专为建筑施工领域打造的一体化信息管理平台,利用大数据、云计算、物联网等技术,实现施工区域各系统数据汇总与可视化管理。平台涵盖人员、设备、物料、环境等关键因素的实时监控与数据分析,提供远程指挥、决策支持等功能,提升工作效率,促进产业信息化发展。系统由PC端、APP移动端及项目、监管、数据屏三大平台组成,支持微服务架构,采用Java、Spring Cloud、Vue等技术开发。
|
2月前
|
人工智能 前端开发 Java
Spring AI Alibaba + 通义千问,开发AI应用如此简单!!!
本文介绍了如何使用Spring AI Alibaba开发一个简单的AI对话应用。通过引入`spring-ai-alibaba-starter`依赖和配置API密钥,结合Spring Boot项目,只需几行代码即可实现与AI模型的交互。具体步骤包括创建Spring Boot项目、编写Controller处理对话请求以及前端页面展示对话内容。此外,文章还介绍了如何通过添加对话记忆功能,使AI能够理解上下文并进行连贯对话。最后,总结了Spring AI为Java开发者带来的便利,简化了AI应用的开发流程。
902 0
|
2月前
|
前端开发 Java 开发者
这款免费 IDEA 插件让你开发 Spring 程序更简单
Feign-Helper 是一款支持 Spring 框架的 IDEA 免费插件,提供 URL 快速搜索、Spring Web Controller 路径一键复制及 Feign 与 Controller 接口互相导航等功能,极大提升了开发效率。
|
2月前
|
XML JSON Java
Spring Boot 开发中常见的错误
本文总结了 Java 开发中常见的几个问题及其改进方法,包括:1. 过度使用 `@Component` 注解;2. `@ResponseBody` 注解的错误用法;3. `@Autowired` 的不当使用;4. `application.properties` 管理不善;5. 异常处理不当。每部分详细解释了错误情况和建议的改进方案,并提供了相应的代码示例。
69 11
|
2月前
|
IDE Java 测试技术
互联网应用主流框架整合之Spring Boot开发
通过本文的介绍,我们详细探讨了Spring Boot开发的核心概念和实践方法,包括项目结构、数据访问层、服务层、控制层、配置管理、单元测试以及部署与运行。Spring Boot通过简化配置和强大的生态系统,使得互联网应用的开发更加高效和可靠。希望本文能够帮助开发者快速掌握Spring Boot,并在实际项目中灵活应用。
80 5
|
2月前
|
XML Java 数据格式
Spring Boot 开发中的常见失误
本文深入分析了Spring Boot开发中常见的失误,包括不当使用@Component、@ResponseBody、@Autowired注解,以及不良的异常处理和日志记录实践,提供了有效的规避策略,帮助开发者提升代码质量和系统性能。
|
3月前
|
前端开发 JavaScript Java
如何使用 Spring Boot 和 Angular 开发全栈应用程序:全面指南
如何使用 Spring Boot 和 Angular 开发全栈应用程序:全面指南
75 1