Java @Schema 与 @ApiModel 注解的演进与对应关系

引言

在整理公司历史文档时，我注意到了 @Schema 注解，由于对其具体用途不够熟悉，因此查阅了相关资料，并将学习心得整理如下。

起初搜索到的信息有限，后经深入查询发现，该注解实际上与之前常用的 @ApiModel 注解密切相关。前者是 Swagger3 推荐使用的注解，而后者则是 Swagger2 时代的常用注解。

在 Swagger2 中，主要使用以下五个核心注解：

最常用的5个注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
 
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
 
 
其它若干
@ApiResponse：HTTP响应其中1个描述
 
@ApiResponses：HTTP响应整体描述
 
@ApiClass
 
@ApiError
 
@ApiErrors
 
@ApiParamImplicit
 
@ApiParamsImplicit

使用 Swagger3 注释替换 Swagger2 注释

该功能已包含在 springdoc-openapi-ui 依赖项中。Swagger3 注释所在的包路径为 io.swagger.v3.oas.annotations。

依赖配置如下：

使用 Swagger3 仅需引入一个核心依赖即可。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

从 Swagger2 迁移至 Swagger3 的变化规则如下：

@Api → @Tag @ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden @ApiImplicitParam → @Parameter @ApiImplicitParams → @Parameters @ApiModel → @Schema @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY) @ApiModelProperty → @Schema @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar") @ApiParam → @Parameter @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

此外，我还向 GPT4 进行了咨询：

今天又学到一个新注解@schema,加油

总结

到此这篇关于Java @Schema和@ApiModel等注解联系的文章就介绍到这了,更多相关@Schema和@ApiModel注解内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！