8.Spring Boot2.5 实战 API 帮助文档 Swagger1|学习笔记

简介: 快速学习8.Spring Boot2.5 实战 API 帮助文档 Swagger1。

开发者学堂课程【Spring Boot 2.5.x 开发实战:8.Spring Boot2.5 实战 API 帮助文档 Swagger1】学习笔记,与课程紧密联系,让用户快速学习知识。

课程地址:https://developer.aliyun.com/learning/course/853/detail/14073


8.Spring Boot2.5 实战 API 帮助文档 Swagger1

 

内容介绍:

一、REST API 帮助文档

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

三、Spring Auto REST Docs

 

一、REST API帮助文档

1.介绍

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

Swagger 是自动化 API 文档的生成工具,该工具之前是Spring Boot项目来进行集成,现在使用 Spring Boot 项目做后端开发,写API的代码的机会较多。

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

对于后端开发来说,不需要自己专门写一套 word 文档,发给前端,前端再去测试,再调进来后台 API。Swagger 文档部署完以后,前端可以直接拿到,然后进行在线调试,非常方便。简化前后端协助,协助避免出错。 (前后端分离的体系非常成熟和完善,一切开发目的主要是为了提升效率,快速的为业务团队服务)

图片14.png


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

图片13.png

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

 图片12.png

2.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

3.Spring REST Docs 的优点:

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

4.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 实例。

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

6.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

1.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

2.Spring Rest Docs 实战 

图片11.png

3.Asciidocs Maven Plugins

image.png

Spring REST Docs 可以在线方便的调试自己的 API,但是没有 Swagger 使用方便

4.Spring Boot 2.0 实战Swagger 

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

页面打开两种方式:

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

(1)/v2/api-docs  

(2)2 Swagger UI /swagger-ui.html  

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

5.Swagger-core 注解

名称

描述

@Api

Marks a class as a Swagger resource.

@ApiModel

Provides additional information about Swagger models.

@ApiModelProperty

Adds and manipulates data of a model property.

ApiOperation

Describes an operation or typically an HTTP method against a specificpath.

@ApiParam

Adds additional meta-data for operation parameters.

@ApiResponse

Describes a possible response of an operation.

@ApiResponses

A wrapper to allow a list of multiple ApiResponse objects.

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

6.Spring Boot 2.0 Rest API 注解 

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

7.实战

该项目可以直接启动,打开项目的配置地址8081

然后刷新页面如下:

image.png

上图可以看出,模拟了订单接口和用户接口。

选择一个接口进入:

图片10.png

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

post 可以看到提交的例子:

image.png

看到上图格式为 json ,这时还可以测试去尝试提交(较方便,可以在线完成该功能)

下图可以看到如果出错,其出错的问题可以显示:

(401无授权、403禁止、404找不到)

image.png

测试 get (模拟查询订单)

下图表示不需要传入数据(空数据)

image.png

点击 try out(尝试执行并执行,可以用 curl 工具进行测试,也可以用浏览器进行测试)

curl 工具进行测试:

image.png

浏览器进行测试:

image.png

注意:

Error 表示错误,Response boby 表示请求消息,Rerponse headers 表示应答消息的消息头

image.png

查看代码发现返回实际没有订单:

return oderRepository.getAll();

但是 user 中有订单,所以可以用  user 库中 get 查询:

image.png

这里返回的有地址、年龄等

这里的数据在控制器中写入,不能改变。(在控制器中的返回参数)

执行后地址:

image.png

应答消息:

image.png

上图内容中写到 “Not Found“,通过查询来验证是否有该问题。

查询:

image.png

说明地址有问题

查看代码看到有生成列表,复制该列表,在 test 中设置了 test 的控制器,将其他参数舍弃,只返回列表(该列表中只有一个用户)

(注意:在新项目尝试过程中出现错误是正常的)

输入地址:

image.png

查询

image.png

该错误是没有明确的映射

在 Swaggerer2Config.java 中加了 Docket ,向控制器中进行扫描,发现上面测试时的错误是因为将注解写错了,要用 RestController。

(构建 API 应用时,最简单的的是用 RestController)

所以改正需要使用 RestController,不要是用 Controller ,再进行页面刷新,重复上面测试的操作。

test 接口测试(get):

image.png

(传输的编码用 chunked ,块模式)

返回 json 的对象,这里就是返回一个列表。

浏览器测试正常:

image.png

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

(注意传入的数据,返回可以构造 list 对象)

Swagger 功能非常强大,也方便调试开发,尤其是前后端分离的架构。

相关文章
|
缓存 监控 前端开发
顺企网 API 开发实战:搜索 / 详情接口从 0 到 1 落地(附 Elasticsearch 优化 + 错误速查)
企业API开发常陷参数、缓存、错误处理三大坑?本指南拆解顺企网双接口全流程,涵盖搜索优化、签名验证、限流应对,附可复用代码与错误速查表,助你2小时高效搞定开发,提升响应速度与稳定性。
|
缓存 自然语言处理 API
阿里巴巴国际站关键字搜索 API 实战:3 步搞定多语言适配 + 限流破局,询盘量提升 40%
跨境电商API开发常陷合规、多语言、限流等坑。本文详解从国际合规(GDPR/CCPA)到参数优化、数据结构化及区域化搜索的全链路方案,附Python代码模板与缓存重试架构,助力提升调用成功率至99%+,精准询盘增长42%。
|
Cloud Native 算法 API
Python API接口实战指南:从入门到精通
🌟蒋星熠Jaxonic,技术宇宙的星际旅人。深耕API开发,以Python为舟,探索RESTful、GraphQL等接口奥秘。擅长requests、aiohttp实战,专注性能优化与架构设计,用代码连接万物,谱写极客诗篇。
2213 1
Python API接口实战指南:从入门到精通
|
开发者 API 机器学习/深度学习
淘宝 / 1688 / 义乌购图搜 API 实战指南:接口调用与商业场景应用
本文详解淘宝、1688、义乌购三大平台图片搜索接口的核心特点、调用流程与实战代码。涵盖跨平台对比、参数配置、响应解析及避坑指南,支持URL/Base64上传,返回商品ID、价格、销量等关键信息,助力开发者快速实现商品识别与比价功能。
淘宝 / 1688 / 义乌购图搜 API 实战指南:接口调用与商业场景应用
|
人工智能 运维 监控
阿里云 API 聚合实战:破解接口碎片化难题,3 类场景方案让业务响应提速 60%
API聚合破解接口碎片化困局,助力开发者降本增效。通过统一中间层整合微服务、第三方接口与AI模型,实现调用次数减少60%、响应提速70%。阿里云实测:APISIX+函数计算+ARMS监控组合,支撑百万级并发,故障定位效率提升90%。
1001 0
|
存储 缓存 NoSQL
Spring Boot2.5 实战 MongoDB 与高并发 Redis 缓存|学习笔记
快速学习 Spring Boot2.5 实战 MongoDB 与高并发 Redis 缓存
Spring Boot2.5 实战 MongoDB 与高并发 Redis 缓存|学习笔记
|
Java Go Nacos
3.10 Spring Cloud Gateway 实战接入 Nacos 服务 | 学习笔记
快速学习 3.10 Spring Cloud Gateway 实战接入 Nacos 服务 。
3.10 Spring Cloud Gateway 实战接入 Nacos 服务 | 学习笔记
|
Cloud Native Java 测试技术
3.9 Spring Cloud Gateway 微服务新网关实战| 学习笔记
快速学习 3.9 Spring Cloud Gateway 微服务新网关实战。
3.9 Spring Cloud Gateway 微服务新网关实战| 学习笔记
|
Java Spring 容器
SpringBoot自动配置的原理是什么?
Spring Boot自动配置核心在于@EnableAutoConfiguration注解,它通过@Import导入配置选择器,加载META-INF/spring.factories中定义的自动配置类。这些类根据@Conditional系列注解判断是否生效。但Spring Boot 3.0后已弃用spring.factories,改用新格式的.imports文件进行配置。
1643 0