最新要闻
- 世界速读:对话丨财通基金朱海东:市场情绪影响沪深300近期走势,仍看好A股
- 全球观点:19岁MIT辍学,26岁的他干出个500亿独角兽
- Win11 23H2更新确认秋季推出!功能更新数量少了
- 世界微速讯:你会买么?调查显示超76%玩家不看好索尼新掌机
- 《小美人鱼》在多国遭遇集体刷差评 女主假发造价15万美元
- 不是手游、不抽角色!国产大作《影之刃零》官宣为买断单机游戏|快播报
- 天天微动态丨日版任天堂Switch OLED版618抄底价:到手1817元
- 时讯:余承东放出豪言:问界年产上千万 做世界第一
- 快看:充满80%仅需30分钟!7座理想4C超级充电站上线
- 打造全国一流职教发展共同体,深职院与深圳二职签约合作办学
- 有梦想就了不起!高考307分女孩考研逆袭211:还将继续攻读博士
- 累计被扣78分 男子酒驾被查:自述“我平时是个老实人”
- 全球时讯:血糖健康开拓者!华为WATCH4 Pro评测:全面的腕上守护专家
- 女性出现这7个症状要小心尿路感染:再忙也要去医院看看!-世界速递
- 全球头条:山东一公司要求员工签自愿放弃社保承诺书 同事:不签担心被挤兑
- 2023天津和平四平东道小学转学通知
手机
iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
- 警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- 男子被关545天申国赔:获赔18万多 驳回精神抚慰金
- 3天内26名本土感染者,辽宁确诊人数已超安徽
- 广西柳州一男子因纠纷杀害三人后自首
- 洱海坠机4名机组人员被批准为烈士 数千干部群众悼念
家电
全球要闻:SpringBoot集成Swagger3.0(详细)
一:前言
Swagger 是一个 RESTful API 的开源框架,它的主要目的是帮助开发者设计、构建、文档化和测试 Web API。Swagger 的核心思想是通过定义和描述 API 的规范、结构和交互方式,以提高 API 的可读性、可靠性和易用性,同时降低 API 开发的难度和开发者之间的沟通成本。
这里我采用了Swagger3.0(Open API 3.0)的方式集成到SpringBoot。springfox-boot-start和springfox-swagger2都是基于Swagger2.x的。这里将介绍springdoc-openapi-ui,它是SpringBoot基于Open API 3.0(Swagger3.0)
有兴趣的可以看看第一章介绍,若直接上手看第二章集成Swagger3.0
(资料图片)
1:Swagger发展史
Swagger它最初由Tony Tam在2011年创建,并在之后被SmartBear Software公司收购。在过去几年中,Swagger经历了许多重大的更新和变化,其发展史大概可以分为以下几个阶段: ①:Swagger 1.x 阶段(2011-2014年)Swagger最初是一个简单的API文档生成工具,通过对JAX-RS和Jersey注解的支持自动生成API文档,使得API文档的维护变得更加容易。 在这个阶段,Swagger还没有完全成熟,只能支持基本的API描述和文档生成。 ②:Swagger 2.x 阶段(2014-2017年)在Swagger 2.x阶段,Swagger发生了重大变化。它不再仅仅是一个文档生成工具,而是一个完整的API开发和管理平台。Swagger 2.x加 入了强大的注解支持,可以描述API的细节信息,如请求参数、返回类型等,以及定义RESTful API的元数据,如API描述、标签等。 此外,Swagger 2.x还引入了OpenAPI规范,在API定义方面有了更严格的标准和规则。 ③:OpenAPI 阶段(2017-至今)(也被称为Swagger 3.x)在2017年,Swagger 2.x的规范成为了Linux基金会旗下的OpenAPI规范。这标志着Swagger从一款工具演变成为了一个开放且标准的API 定义框架。OpenAPI规范不仅继承了Swagger 2.x的特性,还提供了更加全面和严格的API定义规范,并且扩展了对非RESTful API的支持 随着OpenAPI规范的普及,越来越多的API开发者开始使用Swagger/OpenAPI来开发、测试和文档化他们的RESTful API。 所以,随着Linux基金会旗下的OpenAPI收购了Swagger2.x后对其进行了更严格的规范,又进行了各种优化, 所以我们也可以称OpenAPI是一个全新的Swagger3.x,因为OpenAPI对其作了更多的优化和规范。除了上述几个主要阶段之外,还有一些其他重要的事件和版本,如Swagger UI、Swagger Codegen、SwaggerHub等等。这些工具和服务进一步扩展了Swagger的功能,使其成为了一个更加完整、强大和易于使用的API定义和管理平台。
2:Swagger其它介绍
其实OpenAPI规范(也称为 Swagger 3.x 规范)是一种用于描述RESTful API的标准化格式,它定义了如何描述API的基本信息、结构、参数、响应等方面的规范。OpenAPI规范以机器可读的方式定义了RESTful API的结构和特征,支持自动生成文档、客户端与服务端代码、Mock Server和测试工具等。
OpenAPI规范最初由开发Swagger的团队在2010年推出,从Swagger 2.0开始,Swagger规范被正式更名为OpenAPI规范,并得到了许多社区的支持和贡献。OpenAPI规范采用JSON或YAML格式编写,并支持多种数据类型,可以描述API的基本信息、路径、HTTP方法、参数、响应等各种细节。通过遵循OpenAPI规范,开发者可以快速定义和构建RESTful API,并且可以生成相应的文档和代码来帮助他们更快地开发与测试API。同时,OpenAPI规范还可以促进不同系统之间的交互和集成,因为根据规范定义的API可以被多个客户端程序和服务端程序所理解和使用。
OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后,Swagger规范正式更名为OpenAPI规范,并且根据OpenAPI规范的版本号进行了更新。因此,Swagger 3.0对应的就是OpenAPI 3.0版本,它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比,Swagger 3.0更加强调对RESTful API的支持和规范化,提供了更丰富和灵活的定义方式,并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。
3:SpringFox工具(不推荐)
Springfox是一套可以帮助Java开发者自动生成API文档的工具,它是基于Swagger 2.x基础上开发的。Swagger已经成为了RESTful API文档生态系统的事实标准,而Springfox是一个用于集成Swagger2.x到Spring应用程序中的库。而且Springfox提供了一些注解来描述API接口、参数和返回值,并根据这些信息生成Swagger UI界面,从而方便其他开发人员查看和使用您的API接口。此外,Springfox还支持自动生成API文档和代码片段,简化了开发人员的工作量。除了集成Swagger 2.x,Springfox还提供了一些额外功能,例如自定义Swagger文档、API版本控制、请求验证等等。这些功能使得Springfox可以胜任各种类型和规模的应用程序,同时还可以提高代码质量和开发效率。总之,Springfox是一个非常有用的工具,它可以帮助Java开发者快速、简单地集成Swagger2.x,并为他们的应用程序生成高质量的API文档。无论您开发的是大型企业应用程序还是小型服务,使用Springfox都能够提高团队的生产力和代码质量。
注意:但是随着时间的推移,Swagger2.x终究成为历史,所以我们可以看出springfox-boot-starter的坐标从3.0.0版本(2020年7月14日)开始就一直没有更新;也得注意的是springfox-swagger2坐标和springfox-boot-start是一样的,但springfox-boot-start只有3.0.0版本。这里我就不在使用Swagger2.x版本,具体可以在网上找到许多,因为大部分的网上资料都是Swagger2.x的方式。
4:SpringDoc工具(推荐)
SpringDoc对应坐标是springdoc-openapi-ui,它是一个集成Swagger UI和ReDoc的接口文档生成工具,在使用上与springfox-boot-starter类似,但提供了更为灵活、功能更加强大的工具。其中除了可以生成Swagger UI风格的接口文档,还提供了ReDoc的文档渲染方式,可以自动注入OpenAPI规范的JSON描述文件,支持OAuth2、JWT等认证机制,并且支持全新的OpenAPI 3.0规范。
SpringDoc是基于OpenAPI 3.0规范构建的,因此推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中,springdoc-openapi-ui库已被广泛应用,并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本,可以使用springfox-boot-starter库来集成Swagger2.x。
SpringDoc是有着更加先进的技术架构和更好的扩展性,使得其逐渐取代了springfox-boot-starter工具包,成为了当前Spring Boot生态中最受欢迎的API文档工具之一。同时springdoc-openapi-ui还拥有更为完善的开发文档和社区支持,从而吸引了越来越多的开发者加入到这个项目中。因此作为一个Spring Boot开发者,如果想要快速、方便地生成符合OpenAPI 3.0规范的接口文档,建议使用springdoc-openapi-ui这个优秀的工具。
二:SpringBoot集成Open API 3.0(Swagger3.0)
具体参考Gitee:https://gitee.com/ant-laddie/hard-working-ant(OpenAPI_3_Demo_Swagger3项目)
我们在SpringBoot中想集成Swagger3.0,一般不选择原生的Maven坐标,而是选择 springdoc-openapi-ui的Maven坐标,它可以很好的和Spring或SpringBoot项目集成;这个坐标也被Spring社区广泛支持和认可,并被认为是集成Swagger UI和OpenAPI规范的一个优秀选择。下面将直接介绍使用。
1:引入Maven依赖
说明:上面的坐标内部导入了Swagger3.0的原生依赖(我们只需要在SpringBoot导入springdoc-openapi-ui即可) ①:io.swagger.core.v3:swagger-core:2.2.9Swagger Core是Swagger 3.x规范的核心实现,提供了一组Java API,用于生成和处理OpenAPI规范文件。 它包括Swagger的核心功能,例如Model、Schema、Parameter、Response等,是构建Swagger API的必要条件。 ②:io.swagger.core.v3:swagger-annotations:2.2.9Swagger Annotations是一个用于编写Swagger API文档的Java注解库,提供了一组注解,用于描述API元数据。 例如,@Operation、@Parameter、@ApiResponse等注解基本包含了OpenAPI规范中的所有元素。 ③:io.swagger.core.v3:swagger-models:2.2.9Swagger Models是Swagger 3.x规范的Java模型库,提供了一组Java模型类,用于表示OpenAPI规范文件。 它包含了OpenAPI规范中的所有数据模型,例如PathItem、Operation、Parameter、Components等。 org.springdoc springdoc-openapi-ui 1.7.0
2:配置SwaggerOpenApiConfig(配置类方式)
注:io.swagger.v3.oas.annotations 是Swagger注解包,而io.swagger.v3.oas.models是Swagger配置类对象方式
其实我们通过配置类的方式创建一个OpenAPI的Bean对象就可以创建Swagger3.0的文档说明,下面我就直创建。
OpenAPI对象是Swagger中的核心类之一,用于描述整个API的结构和元数据。可以理解为一个API文档对象,其中包含了许多元素,如: ①:openapi属性:表示使用的 OpenAPI 规范版本(例如 3.0.1)。 ②:info属性:表示API的基本信息,包括标题、版本号、描述、联系人等。使用Info类来创建这个对象。 ③:servers属性:表示服务器地址或者URL模板列表。每个URL模板可以包含占位符,这些占位符可以被路径参数或者查询参数替换。 使用Server类来创建这个对象。 ④:paths属性(推荐使用注解方式,不推荐使用配置类配置):表示API的所有路径和操作信息,使用PathItem类来描述每一个路径,使用Operation类来描述操作。 ⑤:components属性:表示API的组件信息,比如响应模板、请求模板和安全方案等。 使用Schema、Response、Parameter、SecurityScheme等类来创建这些对象。 ⑥:tags属性:表示API的标签信息,用于对相似的操作进行分组。 ⑦:addServersItem(Server server)方法:向servers属性中添加一个Server对象。 ⑧:addPaths(String name, PathItem pathItem)方法:向paths属性中添加一个PathItem对象,其中name参数表示路径模板。 ⑨:addTag(Tag tag)方法:向tags属性中添加一个Tag对象。 ⑩:setComponents(Components components)方法:设置components属性的值。
import io.swagger.v3.oas.models.OpenAPI;import io.swagger.v3.oas.models.info.Contact;import io.swagger.v3.oas.models.info.Info;import io.swagger.v3.oas.models.info.License;import org.springframework.boot.SpringBootConfiguration;import org.springframework.context.annotation.Bean;import java.util.HashMap;/** 这是一个普通的Swagger配置文档,其中不包含API接口的配置(API接口的配置推荐使用注解方式)* @author Anhui OuYang * @version 1.0 **/@SpringBootConfigurationpublic class SwaggerOpenApiConfig { /*** * 构建Swagger3.0文档说明 * @return 返回 OpenAPI */ @Bean public OpenAPI customOpenAPI() { // 联系人信息(contact),构建API的联系人信息,用于描述API开发者的联系信息,包括名称、URL、邮箱等 // name:文档的发布者名称 url:文档发布者的网站地址,一般为企业网站 email:文档发布者的电子邮箱 Contact contact = new Contact() .name("蚂蚁小哥") // 作者名称 .email("xiaofeng@qq.com") // 作者邮箱 .url("https://www.cnblogs.com/antLaddie/") // 介绍作者的URL地址 .extensions(new HashMap()); // 使用Map配置信息(如key为"name","email","url") // 授权许可信息(license),用于描述API的授权许可信息,包括名称、URL等;假设当前的授权信息为Apache 2.0的开源标准 License license = new License() .name("Apache 2.0") // 授权名称 .url("https://www.apache.org/licenses/LICENSE-2.0.html") // 授权信息 .identifier("Apache-2.0") // 标识授权许可 .extensions(new HashMap ());// 使用Map配置信息(如key为"name","url","identifier") //创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license) Info info = new Info() .title("Swagger3.0 (Open API) 框架学习示例文档") // Api接口文档标题(必填) .description("学习Swagger框架而用来定义测试的文档") // Api接口文档描述 .version("1.2.1") // Api接口版本 .termsOfService("https://example.com/") // Api接口的服务条款地址 .license(license) // 设置联系人信息 .contact(contact); // 授权许可信息 // 返回信息 return new OpenAPI() .openapi("3.0.1") // Open API 3.0.1(默认) .info(info); // 配置Swagger3.0描述信息 }}
3:配置SwaggerOpenApiConfig(注解方式)
上面我们使用了Java代码创建Bean的方式,其实这种写起来感觉还行,但是在使用了注解方式是很舒服的,下面就简单说明:
定义Swagger3.0配置信息注解:@OpenAPIDefinition (具体参考 io.swagger.v3.oas.annotations)注意:这个注解全局只能配置一个,主要配置文档信息和安全配置 说明:用于描述整个API的元信息和全局属性,可以定义和描述,包括API版本、基本信息、服务器信息、安全方案等 常用属性: ①:info:用于描述 API 基本信息的对象,包括标题、版本号、描述等属性; ②:servers:用于描述 API 服务的 URL 和配置信息的数组; ③:security:用于描述 API 安全方案的数组,其中每个安全方案包含多个安全需求; ④:tags:用于描述 API 标签的数组,每个标签包含名称、描述等属性; ⑤:externalDocs:用于描述外部文档链接的对象,包含描述和 URL 两个属性。
import io.swagger.v3.oas.annotations.ExternalDocumentation;import io.swagger.v3.oas.annotations.OpenAPIDefinition;import io.swagger.v3.oas.annotations.info.Contact;import io.swagger.v3.oas.annotations.info.Info;import io.swagger.v3.oas.annotations.info.License;import io.swagger.v3.oas.annotations.servers.Server;import org.springframework.boot.SpringBootConfiguration;/** * @author Anhui OuYang * @version 1.0 **/@SpringBootConfiguration@OpenAPIDefinition( // ## API的基本信息,包括标题、版本号、描述、联系人等 info = @Info( title = "Swagger3.0 (Open API) 框架学习示例文档", // Api接口文档标题(必填) description = "学习Swagger框架而用来定义测试的文档", // Api接口文档描述 version = "1.2.1", // Api接口版本 termsOfService = "https://example.com/", // Api接口的服务条款地址 contact = @Contact( name = "蚂蚁小哥", // 作者名称 email = "xiaofeng@qq.com", // 作者邮箱 url = "https://www.cnblogs.com/antLaddie/" // 介绍作者的URL地址 ), license = @License( // 设置联系人信息 name = "Apache 2.0", // 授权名称 url = "https://www.apache.org/licenses/LICENSE-2.0.html" // 授权信息 ) ), // ## 表示服务器地址或者URL模板列表,多个服务地址随时切换(只不过是有多台IP有当前的服务API) servers = { @Server(url = "http://192.168.2.235/demo/", description = "本地服务器一服务"), @Server(url = "http://192.168.2.236/demo/", description = "本地服务器二服务"), }, externalDocs = @ExternalDocumentation(description = "更多内容请查看该链接", url = "xxx"))public class SwaggerOpenApiConfig {}
4:配置API接口信息(注解,重要)
说了这么久,Swagger3.0的全局基本信息配置是处理好了,接下来就是配置接口了,因为我之前写了Controller代码,但是没有接口配置信息,这里我就使用Swagger的方式进行一个简单的配置。
### 示例代码,不是太明白属性的可以看下面属性介绍(具体的代码需要查看git)
// 响应对象模型定义@Data@AllArgsConstructor@Schema(description = "响应返回数据对象")public class AjaxResult { @Schema( title = "code", description = "响应码", format = "int32", requiredMode = Schema.RequiredMode.REQUIRED ) private Integer code; @Schema( title = "msg", description = "响应信息", accessMode = Schema.AccessMode.READ_ONLY, example = "成功或失败", requiredMode = Schema.RequiredMode.REQUIRED ) private String msg; @Schema(title = "data", description = "响应数据", accessMode = Schema.AccessMode.READ_ONLY) private Object data;}
// 模型定义示例:@Data@AllArgsConstructor@Schema(title = "学生模型VO", description = "响应视图学生模型VO")public class StudentVO { @Schema(name = "学生ID", description = "学生ID属性", format = "int64", example = "1") private Long id; // 学生ID @Schema(name = "学生姓名", description = "学生姓名属性", example = "jack") private String name; // 学生姓名 @Schema(name = "学生年龄", description = "学生年龄属性", format = "int32", example = "24") private Integer age; // 学生年龄 @Schema(name = "学生地址", description = "学生地址属性", example = "安徽合肥") private String address; // 学生地址 @Schema(name = "学生分数", description = "学生分数属性", format = "double", example = "55.50") private Double fraction; // 学生分数 @Schema(name = "学生爱好", description = "学生爱好属性(List类型)", type = "array", example = "[\"玩\", \"写字\"]") private Listlikes; // 学生爱好}
// 接口定义@RestController@RequestMapping("/student")@Tag( name = "StudentControllerAPI", description = "学生控制器接口", externalDocs = @ExternalDocumentation( description = "这是一个接口文档介绍", url = "https://www.cnblogs.com/antLaddie/"))public class StudentController { /*** * 根据ID查询学生信息(单条) * @param id 学生id * @return 返回一条数据 */ @Operation( summary = "根据Id查询学生信息", description = "根据ID查询学生信息,并返回响应结果信息", parameters = { @Parameter(name = "id", description = "学生ID", required = true, example = "1") }, responses = { @ApiResponse( responseCode = "200", description = "响应成功", content = @Content( mediaType = "application/json", schema = @Schema( title = "AjaxResul和StudentVO组合模型", description = "返回实体,AjaxResult内data为StudentVO模型", anyOf = {AjaxResult.class, StudentVO.class}) ) ), @ApiResponse( responseCode = "500", description = "响应失败", content = @Content( mediaType = "application/json", schema = @Schema( title = "AjaxResul模型", description = "返回实体,AjaxResult内data为空", implementation = AjaxResult.class) ) ) } ) @GetMapping("/findOne/{id}") public AjaxResult findOneStudent(@PathVariable(value = "id") Long id) { //模拟学生数据 List### 配置文档标题及归类,就是在Controller上配置。likes = Arrays.asList("抓鱼", "爬山", "写字"); StudentVO studentVO = new StudentVO(id, "张三", 22, "安徽六安", 93.5, likes); return new AjaxResult(200, "成功", studentVO); } /*** * 查询全部学生数据 * @return 返回d条数据 */ @Operation( summary = "查询全部学生数据", description = "查询学生信息,并返回响应结果信息", parameters = {}, deprecated = true, responses = { @ApiResponse( responseCode = "200", description = "响应成功", content = @Content( mediaType = "application/json", schema = @Schema( title = "AjaxResul和StudentVO组合模型", description = "返回实体,AjaxResult内data为" + "StudentVO模型(并且StudentVO为集合)", anyOf = {AjaxResult.class, StudentVO.class}) ) ) } ) @GetMapping("/findAll") public AjaxResult findAllStudent() { //模拟学生数据 List likes = Arrays.asList("抓鱼", "爬山", "写字"); StudentVO student1 = new StudentVO(1L, "张三", 22, "安徽六安", 93.5, likes); StudentVO student2 = new StudentVO(2L, "李四", 24, "安徽合肥", 99.5, likes); return new AjaxResult(200, "成功", Arrays.asList(student1, student2)); } /*** * 学生添加接口 * @param studentDTO 学生DTO信息 * @return 成功信息 */ @Operation( summary = "学生添加接口", description = "学生添加接口", parameters = {}, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody( description = "学生信息DTO", required = true, content = { @Content( mediaType = "application/json", schema = @Schema(implementation = StudentDTO.class) ) } ), responses = { @ApiResponse( responseCode = "200", description = "响应成功", content = @Content( mediaType = "application/json", schema = @Schema( title = "AjaxResul模型", description = "返回实体AjaxResult,并且Data为null", implementation = AjaxResult.class) ) ) } ) @PostMapping("/saveStudent") public AjaxResult saveStudent(@RequestBody StudentDTO studentDTO) { System.out.println("成功添加数据:" + studentDTO); return new AjaxResult(200, "成功", null); } ........ 省略}
注解:@Tag 可以用于对接口进行分类和归类,便于开发人员组织和管理 API 文档 具体属性: ①:name:表示标签的名称,必填属性,也得注意多个Controller上的name不要写一样的,这样就会把它们归类在一起。 ②:description:表示标签的描述信息,非必填属性。 ③:externalDocs:用于指定URL地址文档信息来追加描述接口的信息。非必填属性。 示例: @Tag( name = "StudentControllerAPI", description = "学生控制器接口", externalDocs = @ExternalDocumentation( description = "这是一个接口文档介绍", url = "https://www.cnblogs.com/antLaddie/"))
### 配置文档下的每一个接口信息,就是Controller里的每一个RequestMapping
注解:@Operation用于对API操作(即方法)进行描述和标记。就是我们熟知的Controller下的一个个请求的方法上。 具体可以参考 io.swagger.v3.oas.annotations。 具体属性: ①:summary:用于简要描述API操作的概要。 ②:description:用于详细描述API操作的描述信息。 ③:parameters:用于指定API操作的参数列表,包括路径参数、请求参数、请求头部等。可以使用@Parameter注解进一步定义参数。 ④:operationId:用于指定API操作的唯一标识符,可以用于生成客户端代码或文档等。 说明:第三方工具使用operationId来唯一标识此操作。(具体我也没用过) ⑤:requestBody:用于定义API操作的请求体,可以使用@RequestBody注解进一步定义请求体。 说明:这里的@RequestBody注解是@io.swagger.v3.oas.annotations.parameters.RequestBody包里的 ⑥:responses:用于定义 API 操作的响应列表,包括成功响应和错误响应。可以使用@ApiResponse注解进一步定义响应。 ⑦:security:用于对API操作进行安全控制,可以使用@SecurityRequirement注解进一步定义安全需求。(后面说) ⑧:deprecated:表示该API操作已经过时或不推荐使用。@Operation( summary = "根据Id查询学生信息", description = "根据ID查询学生信息,并返回响应结果信息", parameters = { @Parameter(name = "id", description = "学生ID", required = true, example = "1") }, responses = { @ApiResponse( responseCode = "200", description = "响应成功", content = @Content( mediaType = "application/json", schema = @Schema( title = "AjaxResul和StudentVO组合模型", description = "返回实体,AjaxResult内data为StudentVO模型", anyOf = {AjaxResult.class, StudentVO.class}) ) ) } )
### 配置请求接口参数信息
注解:@Parameter用于描述HTTP请求的参数信息,它是一个Parameter[]类型的数组,每个元素表示一个请求参数; 具体参考:io.swagger.v3.oas.annotations;它是一个注解,和Parameter类一样,只不过一个是注解一个是类的方式 ①:name:参数名称。 ②:in:参数位置,可以是 query、header、path、cookie 等。 ③:description:参数描述。 ④:required:参数是否必须,默认为 false。 ⑤:deprecated:参数是否已过时,默认为 false。 ⑥:allowEmptyValue:是否允许空值,默认为false。 ⑦:style:参数的序列化风格,可以是 "matrix"、"label"、"form"、"simple"、 "spaceDelimited"、"pipeDelimited"、"deepObject"; ⑧:explode:当参数值是对象或数组时,是否将其展开成多个参数,默认为 false。 ⑨:schema:参数类型和格式的定义,通常使用@Schema注解。(下面介绍) ⑩:example:参数值的示例; 示例: parameters = { @Parameter(name = "id", in = ParameterIn.PATH, description = "学生ID", required = true, example = "1") },
### 配置具体的实体模型信息
注解:@Schema 是用于描述数据模型的基本信息和属性,具体可以参考“io.swagger.v3.oas.annotations.media” 具体属性: ①:description:用于描述该类或属性的作用。 ②:name:指定属性名。该属性只对属性有效,对类无效。 ③:title:用于显示在生成的文档中的标题。 ④:requiredMode:用于指定该属性是否必填项。枚举Schema.RequiredMode内可选值如下: 默认AUTO:可有可无;REQUIRED:必须存在此字段(会加红色*);NOT_REQUIRED:不需要存在此字段 ⑤:accessMode:用于指定该属性的访问方式。 包括AccessMode.READ_ONLY(只读)、AccessMode.WRITE_ONLY(只写)、AccessMode.READ_WRITE(读写) ⑥:format:用于指定该属性的数据格式。例如:日期格式、时间格式、数字格式。 ⑦:example:为当前的属性创建一个示例的值,后期测试可以使用此值。 ⑧:deprecated:用于指定该属性是否为已过时的属性,默认为false。 ⑨:defaultValue:用于指定该属性的默认值。 ⑩:implementation:用于显示为该类或属性引入具体的实体路径,这代表当前指定的类或者属性将参考引入的实体。 就是说有个实体类,这个类里面有个teacher属性,这时里面的teacher属性可以指定具体的实体类,如下: public class Student { ... @Schema(description = "老师信息",implementation = Teacher.class) private Teacher teacher; ... } 其它属性: ①:type:用于指定数据类型(Data Type)或者元素类型(Element Type) 基本类型:取值为相应的 Java 类型名,例如 int、long、float、double、boolean 等。 包装类型:与基本类型相同,取值为相应的Java包装类型名,例如Integer、Long、Float、Double、Boolean等。 字符串类型:取值为string。 数组类型:取值为 array。对于数组类型,还可以使用 schema 属性指定其元素类型的 Schema 信息。 对象类型:不用指定type,可以通过implementation属性引入。 枚举类型:取值为enum。对于枚举类型,还需要使用enumAsRef属性指定是否将其定义为一个独立的引用类型。 其它类型:不用指定type,可以通过implementation属性引入。@Schema注解:提供了四个属性来描述复杂类型,分别是allOf、anyOf、oneOf和not。 这四个属性可以用于组合不同的JSON Schema以描述一个复杂类型,具体如下: ①:allOf: 表示当前schema是多个其它schema的并集。 例如,如果一个Java类型同时实现了两个接口,那么可以使用allOf来表示这个Java类型继承了这两个接口的所有属性和方法。 ②:anyOf: 表示当前schema可以匹配其中任意一个schema,其本身也是一个组合体,可以嵌套使用。 例如,一个返回类型可能是多个Java类型中的任意一个,可以使用anyOf来描述这种情况。 ③:oneOf: 表示当前schema只能匹配其中一个schema,其本身也是一个组合体,可以嵌套使用。 例如,一个Java类型只能是多个子类型中的任意一个,可以使用oneOf来描述这种情况。 ④:not: 表示当前Schema不能匹配某个schema。 例如,一个Java类型不能是某个子类型,可以使用not来描述这种情况。 但是总感觉这个Swagger无法满足我特定要求的实体,具体解决如下: 比如我现在有个AjaxResult类(code,msg,data),其中data为Object或其它类型,这时我返回的数据里data为其它类型的 实体,所以我这里不理解如何返回的实体中,通过点击data而显示另外实体,我只能通过anyOf方式来实现(加上注解) @ApiResponse( responseCode = "200", description = "响应成功", content = @Content( mediaType = "application/json", schema = @Schema( description = "返回实体,AjaxResult内data为StudentVO模型", anyOf = {AjaxResult.class, StudentVO.class}) ) )
5:配置API接口信息(定义类方式,不推荐)
上面介绍了使用注解的方式完成接口的说明,这里我来说说定义类的方式来完成接口的定义,其实这种方式不推荐,写起来繁琐麻烦,后期改起来也乱,但是还是说下,下面就是具体的代码信息
/** * 老师接口描述 * * @author Anhui OuYang * @version 1.0 **/public class InterfaceDescriptionConfig { /*** * get方式保存老师信息接口 * @return PathItem */ public static PathItem addTeacher() { //=====================创建字段描述信息(老师类描述)如:TeacherDTO===================== Schema id = new IntegerSchema().format("int64").description("老师ID"); Schema name = new StringSchema().minLength(2).maxLength(5).example("张三").description("老师姓名"); Schema age = new IntegerSchema().format("int32").maximum(new BigDecimal("99")) .minimum(new BigDecimal("1")).example("23").description("老师年龄"); Schema birthday = new DateSchema().format("date").example("2023-12-12").description("老师生日"); Schema address = new StringSchema().minLength(2).maxLength(9).example("安徽省").description("老师地址"); Schema salary = new NumberSchema().format("bigDecimal").maximum(new BigDecimal("99999.99")) .minimum(new BigDecimal("100.00")).example("6500.50").description("老师工资"); Schema fraction = new NumberSchema().format("double").maximum(new BigDecimal("99.99")) .minimum(new BigDecimal("10.00")).example("25.3").description("老师评分"); Schema likes = new ArraySchema().minItems(1).maxItems(10).description("这是一个爱好数组"); Schema isHeadmaster = new BooleanSchema().example(true).description("是否是班主任"); Schema schema = new ObjectSchema().description("老师对象属性") .addProperty("id", id).addProperty("name", name).addProperty("age", age) .addProperty("birthday", birthday).addProperty("address", address) .addProperty("salary", salary).addProperty("fraction", fraction) .addProperty("likes", likes).addProperty("isHeadmaster", isHeadmaster); //=====================响应字段描述信息(返回类描述)如:AjaxResult===================== Schema resultSchema = new ObjectSchema().description("响应信息对象") .addProperty("code", new IntegerSchema().example("200").description("响应码")) .addProperty("msg", new StringSchema().example("成功").description("响应信息")) .addProperty("data", schema); //设置响应头信息,可以设置系统响应头,也可以设置自定义响应头,具体声明,前端好获取指定响应头信息 HashMap接口及模型的描述(使用定义类的方式)headers = new HashMap<>(); headers.put("my-header1", new Header().description("测试响应头1").schema(new StringSchema())); headers.put("my-header2", new Header().description("测试响应头2").schema(new StringSchema())); headers.put("my-header3", new Header().description("测试响应头3").schema(new StringSchema())); // 设置响应信息 ApiResponses apiResponses = new ApiResponses() .addApiResponse("200", new ApiResponse().description("响应成功信息").headers(headers) .content(new Content().addMediaType("application/json", new MediaType().schema(resultSchema)))) .addApiResponse("500", new ApiResponse().description("响应失败")); // 设置请求信息 RequestBody requestBody = new RequestBody() .content(new Content().addMediaType("application/json", new MediaType().schema(schema))); // 设置请求URL后缀参数信息(可以添加多个) 接口描述 List parameters = new ArrayList<>(); Parameter sign = new Parameter() .name("sign") // 设置参数名称 .description("URL参数标记信息") // 设置描述 .required(false) // 是否必传 .in("path") // 参数信息参数位置(当前在URL路径后) .schema(new StringSchema()) // 参数类型 .example("tx117839"); // 示例数据 parameters.add(sign); // 设置当前接口描述信息 Operation operation1 = new Operation() .operationId("addTeacher") .description("这是一个添加老师信息的接口") .requestBody(requestBody) .parameters(parameters) .responses(apiResponses); // 设置接口路径信息及请求方式(这里我设置了一个post请求的接口) return new PathItem().post(operation1).description("POST请求"); }}
import io.swagger.v3.oas.models.OpenAPI;import io.swagger.v3.oas.models.Paths;import org.springframework.boot.SpringBootConfiguration;import org.springframework.context.annotation.Bean;/** * @author Anhui OuYang * @version 1.0 **/@SpringBootConfigurationpublic class SwaggerOpenApiConfig1 { /*** * 构建Swagger3.0文档说明 * @return 返回 OpenAPI */ @Bean public OpenAPI customOpenAPI() { // 配置Info信息 ... //通过Paths可以配置多组接口信息(Paths接收PathItem,这里的每个PathItem我抽取方式出去了) Paths paths = new Paths(); paths.put("根据传入的老师信息进行数据保存", InterfaceDescriptionConfig.addTeacher()); // 返回信息 return new OpenAPI() .openapi("3.0.1") // Open API 3.0.1(默认) .paths(paths) .info(null); // 配置Swagger3.0描述信息 }}接口信息的绑定到Swagger中
6:权限认证方式
其实我们的接口都是有权限校验方式的,每个接口在请求时都是包含校验,如我们常见的JWT校验,我们访问每个接口都需要携带Token信息,下面我就简单说说校验认证的方式描述。
注解权限设置:@SecurityScheme (具体参考io.swagger.v3.oas.annotations.security) 说明:用于定义API的安全方案。通过使用@SecurityScheme注解,我们可以为API定义多种安全方案,并指定每种方案的相关属性, 例如认证类型、授权URL、令牌URL、作用域等。 常用属性: ①:name: 安全方案的名称; ②:type: 认证类型,具体包含如下:SecuritySchemeType.API_KEY(API密钥)、SecuritySchemeType.HTTP(HTTP认证)、 SecuritySchemeType.OAUTH2(OAuth2.0 认证)等; ③:description: 安全方案的描述信息; ④:in: 仅在使用API密钥认证时适用,表示API密钥的位置,包括如下: ApiKeyLocation.HEADER(HTTP 头部)、ApiKeyLocation.COOKIE(Cookie)等 ⑤:scheme: 仅在使用HTTP认证时适用,表示认证方案,例如HTTP Authentication Scheme.Basic(Basic 认证); 防止客户端需要在请求头部中添加一个包含用户名和密码的 Base64 编码字符串,并以 "Basic "开头,如: Authorization: Basic YWRtaW46MTIzNDU2 ⑥:bearerFormat: 仅在使用 Bearer Token 认证时适用,表示 Bearer Token 的格式; ⑦:flows: 仅在使用OAuth2.0认证时适用,表示OAuth2.0的认证流程,包括@OAuthFlows.authorizationCode、 @OAuthFlows.clientCredentials、@OAuthFlows.password 和 @OAuthFlows.implicit等。示例:(可以在我们自定义的SwaggerOpenApiConfig内设置权限认证) @SecurityScheme( name = "JWT-test", // 认证方案名称 type = SecuritySchemeType.HTTP, // 认证类型,当前为http认证 description = "这是一个认证的描述详细", // 描述信息 in = SecuritySchemeIn.HEADER, // 代表在http请求头部 scheme = "bearer", // 认证方案,如:Authorization: bearer token信息 bearerFormat = "JWT") // 表示使用 JWT 格式作为 Bearer Token 的格式
比如我添加了一个名称为”JWT-test“的验证方式,使用方式存在2种,一种是设置全部文档使用这种验证,另一种是某个接口使用此种校验方式,具体使用如下:
当前在自定义的SwaggerOpenApiConfig类上面设置了两种权限校验方式,如下:@SecurityScheme( name = "JWT-test", // 认证方案名称 type = SecuritySchemeType.HTTP, // 认证类型,当前为http认证 description = "这是一个认证的描述详细", // 描述信息 in = SecuritySchemeIn.HEADER, // 代表在http请求头部 scheme = "bearer", // 认证方案,如:Authorization: bearer token信息 bearerFormat = "JWT") // 表示使用 JWT 格式作为 Bearer Token 的格式@SecurityScheme( name = "X-API-KEY", type = SecuritySchemeType.APIKEY, description = "这是一个认证的描述详细", in = SecuritySchemeIn.HEADER, scheme = "bearer")设置全部接口描述都有指定的一种校验方式: 在@OpenAPIDefinition注解里的security属性设置校验方式@OpenAPIDefinition( .... security = @SecurityRequirement(name = "JWT-test") )设置指定接口描述有指定的一种校验方式: 在@Operation注解里的security属性设置校验方式@Operation( .... security = @SecurityRequirement(name = "JWT-test") )
三:SpringBoot集成Open API3.0具体运行效果
## 总览
## 学生Controller根据ID查询学生界面
## 模型定义信息
## 权限认证(这里我配置两个在Swagger配置类上)
.
关键词:
-
世界速读:对话丨财通基金朱海东:市场情绪影响沪深300近期走势,仍看好A股
今年4月中旬以来,沪深300指数整体走弱,截至5月24日,沪深300指数收盘3,859 09点,较年初下跌0 75%,[1]这
来源: 全球要闻:SpringBoot集成Swagger3.0(详细)
世界速读:对话丨财通基金朱海东:市场情绪影响沪深300近期走势,仍看好A股
全球观点:19岁MIT辍学,26岁的他干出个500亿独角兽
Win11 23H2更新确认秋季推出!功能更新数量少了
世界微速讯:你会买么?调查显示超76%玩家不看好索尼新掌机
世界聚焦:Doris(三) -- Rollup和物化视图
《小美人鱼》在多国遭遇集体刷差评 女主假发造价15万美元
不是手游、不抽角色!国产大作《影之刃零》官宣为买断单机游戏|快播报
天天微动态丨日版任天堂Switch OLED版618抄底价:到手1817元
时讯:余承东放出豪言:问界年产上千万 做世界第一
快看:充满80%仅需30分钟!7座理想4C超级充电站上线
天天热点评!【一步步开发AI运动小程序】九、姿态辅助调试桌面工具折使用
刷爆的“信用卡”——起底美国债务危机_全球最资讯
每日聚焦:深交所:调整深证成指、创业板指、深证100等指数样本股
打造全国一流职教发展共同体,深职院与深圳二职签约合作办学
有梦想就了不起!高考307分女孩考研逆袭211:还将继续攻读博士
累计被扣78分 男子酒驾被查:自述“我平时是个老实人”
全球时讯:血糖健康开拓者!华为WATCH4 Pro评测:全面的腕上守护专家
女性出现这7个症状要小心尿路感染:再忙也要去医院看看!-世界速递
全球头条:山东一公司要求员工签自愿放弃社保承诺书 同事:不签担心被挤兑
2023天津和平四平东道小学转学通知
11)MySQL编程基础
【Oracle impdp/expdp】Big lesson from failure with impdp/expdp in 12c 焦点要闻
交易商协会:一季度债市信评调整次数下降 负面调整占七成-今日热讯
LCD小金刚!Redmi Note 12T Pro配备12GB大内存、5080mAh电池
iPhone 16 Pro机型屏幕为6.3和6.9英寸 为啥手机屏越来越大? 今日热讯
世界今日报丨2999元起 魅族20斩获京东预售销量TOP4:三年质保行业罕见
苹果WWDC 2023来了!iOS 17把短板都消灭干净了
618会员抄底:百度/腾讯/QQ/京东/B站/爱奇艺等大促合集-环球头条
东莞景湖装饰,家居装修达人_世界报道
Angular Highcharts教程_编程入门自学教程_菜鸟教程-免费教程分享
2、AS400 开发环境
每天一个Linux命令-gunzip. 每日看点
当前聚焦:揭秘“AI换脸”诈骗背后,黑灰产使用的手段
第二单元 常用快捷键,注释,变量
环球动态:香港金管局6月7日拟重启10年期政府债券机构增发
三星GalaxyChromebook2预购价格为$550美元
299元 荣耀Earbuds X5耳机发布:13.4mm超大动圈、27小时续航-世界快看
当前关注:超越朋友圈 微信视频号大升级
每日速递:想入职特斯拉?官方发声明提醒谨防诈骗:未与第三方人力资源合作
比日系品牌识时务!别克大五座中型纯电SUV交付:20.89万起香爆
【全球播资讯】NVIDIA黄仁勋“挑战”CPU:GPU训练AI大模型可降低96%成本
环球观热点:花了亿点点时间,写了一个赶海和茶艺小程序:探索多重功能,开启精彩互动之旅!
环球快消息!不推荐使用Date日期和Calendar日期
10)索引、视图 热讯
章子怡坐廉价航空被偶遇,空姐频打扰身份暴露,穿7000块一条裤子 焦点讯息
天天亮点!收评:创指跌1.14%创逾1年新低 脑机接口概念整体走强
GPT现状终于有人讲清楚了!还得是马斯克钦点的天才-环球视点
全球速读:零风险调光护眼屏 荣耀90系列全球首发3840Hz超高频屏幕技术
江西多地加入“高温群聊” 体感平均温度超40℃
比亚迪和特斯拉的“对垒” 正在进入一个新阶段
环球资讯:荣耀90系列搭载创新动脉仿生VC:首发航天级导热凝胶
实验作文300字_小实验作文300字
当前消息!vue列表逐个进入过渡动画
【世界时快讯】数字化转型,低代码开发真的靠谱?
世界播报:VST实例(3)绘制VST
【快播报】一图胜千言,气泡图引领数据时代的视觉革命
环球视讯!Unity的Console的控制类LogEntries:深入解析与实用案例
天天热资讯!金观平:唱响新时代“黄河大合唱”
专项债券不能“一拨了之”
广告弹窗太多!小米应用商店出手严管WiFi、清理类App
环球快播:100%自研!印度本土4G/5G网络来了:设备将投入大规模部署 还要推广全球
国产大飞机C919商用首飞成功!全机供应链揭秘_环球热讯
减肥就非得痛苦吗?华为鸿蒙3全家桶打造运动健身新体验-全球快报
阻止Wii模拟器登陆Steam!任天堂表态:模拟器非法 当前热点
关于征集载人月球车研制方案的公告
3年来首升!日本应届大学生就业率97.3% 全面复苏争夺汽车、半导体等人才
“礼让行人”该不该被取消 网友吵翻:车主称拿规则当保护伞 你怎么看?|全球观天下
3万多条含图片的菜谱资料ACCESS\EXCEL数据库-天天视讯
聊聊MassTransit——实现Saga模式概览(译)|天天视点
Visual Studio 2022的一个惊艳新功能开发隧道|滚动
嫁给金牛男最多的星座女 金牛男婚后会出轨吗?
PHEV车型常压油箱如何吸附燃油蒸汽?比亚迪公布技术细节 天天关注
Redmi Note 12T Pro搭载罕见LCD原色屏:144Hz超高刷新率
不靠显卡 NVIDIA太会做AI生意了:转手就卖出100倍 环球观焦点
热讯:华为官宣开发者大会 7月7日见:全球第三大手机系统鸿蒙4.0要来了
吸湿速干 反光设计:鸿星尔克男士速干冰丝短袖39元发车
马斯克旗下Neuralink获准启动人体临床试验 脑机接口概念股集体拉升_最资讯
直播源码技术屏幕共享功能
Python压缩JS文件,重点是 slimit
Python工具箱系列(三十四)
环球热头条丨U3DFrameWorkDemo:四、资源打包和热更
焦点日报:基于 Mindspore 框架与 ModelArts 平台的 MNIST 手写体识别实验
神十六有航天飞行工程师和载荷专家:戴眼镜也能上太空了-天天快看点
红魔电竞显示器2K银翼版618优惠300元:240Hz超高刷 环球新消息
头条焦点:12点正式开始!天猫618红包首发 超高概率中现金红包
世界快看:改款将至?曝特斯拉上海工厂Model 3产线停工:价格或将调整
世界今头条!官宣2030年前登月 我国面向全社会征集载人月球车研制方案
丰立智能:5月26日融资净买入2470.32万元,连续3日累计净买入4969.34万元
Docker 学习笔记
过滤器链及责任链设计模式 观热点
阿里一面:MySQL 单表数据最大不要超过多少行?为什么?这样回答满分! 世界热消息
gps网络时间服务器(时间同步装置)助力电力信息化建设|世界观焦点
deepin-for-arm64支持
全球关注:债市观察:利好钝化收益率窄幅波动 十债2.7%踌躇踏步
【世界新视野】抖音打不开视频怎么回事_抖音打不开
当前要闻:山姆同款蛋糕杭州卖165上海卖95 网友直呼太坑:你遇到过吗
绵云般口感!和路雪千层雪冰淇淋3.5元官方大促(商超6元)
今年唯一LCD性能机!Redmi Note 12T Pro外观公布-当前独家
重点聚焦!研究称每天排便超一次或影响健康:心力衰竭风险增加33%