Knife4j使用教程（三） -- 实体类的配置注解（@ApiModel与@ApiModelProperty 的 认识与使用）

已于 2023-10-28 20:29:35 修改
阅读量1.8k 收藏
点赞数 1
分类专栏： # java 工具类 文章标签： java 开发语言 intellij-idea
于 2023-10-27 22:25:37 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/PUYALEI/article/details/134084646
版权
本文介绍了 Knife4j 中的 @ApiModel 和 @ApiModelProperty 注解，用于增强接口实体类的描述。@ApiModel 用于类级别，提供类描述，而 @ApiModelProperty 则用于字段级别，提供字段详细信息。@ApiModelProperty 的属性包括 value、name、required、hidden 和 allowEmptyValue，分别用于字段描述、重命名、是否必填、是否显示及允许空值。

摘要生成于 C知道 ，由 DeepSeek-R1 满血版支持， 前往体验 >

目录

1. @ApiModel与@ApiModelProperty的区分

2. @ApiModel注解

3. @ApiModelProperty注解

3.1 value属性

3.2 name属性

3.3 required 属性

3.4 hidden属性

3.5 allowEmptyValue属性

3.6 example属性

1. @ApiModel与@ApiModelProperty的区分

  1. @ApiModel注解是用在接口相关的实体类上的注解，它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息，常常和@ApiModelProperty注解配合使用。
  2. @ApiModelProperty注解则是作用在接口相关实体类的属性（即，字段）上的注解，
了解本专栏 订阅专栏 解锁全文 超级会员免费看
【SpringBoot】22、SpringBoot中整合knife4j接口文档
Asurplus
07-02 21万+
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护 一、界面先赏 1、首页 2、接口文档 3、调试 二、整合 knife4j 1、引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> &lt
全网最全的Knife4j swaggerj介绍(@Api,@ApiOperation,@ApiImplicitParams,@ApiModel,@ApiModelProperty等）
念兮为美
02-01 2904
全网最全的Knife4j swaggerj介绍(@Api,@ApiOperation,@ApiImplicitParams,@ApiModel,@ApiModelProperty等）
新手必看-Knife4j的常用注解
学习记录
09-04 1867
SpringBoot集成Knife4j可看另一篇文章：http://t.csdnimg.cn/bmPhj 添加在controller类上，可以指定该 controller 模块的名称。knife4j默认根据字母排序，加上序号后会根据序号排序。 该注解放在 controller 类下的请求方法上，可以指定该请求/方法的作用。添加后可以在对应的 控制层模块下查看该请求。 用于对请求方法的参数列表中那些未封装的参数进行说明。如果有多个参数时需要使用@Parameters包起来。
【原创】Knife4j从2.x升级到4.x版本升级方案和措施，并解决SpringBoot3.x无法显示knife4j文档问题，报No static resource swagger-resources
最新发布
DCTANT的博客
02-27 1046
通过这篇文章介绍了Knife4j从2.0.9升级到4.4.0的步骤，并详细介绍了升级方法，还有遇到的故障排除
Knife4j 的基本使用说明
Melody_1943的博客
06-10 1977
Knife4j是一款可以提供在线API文档的框架，是基于Swagger框架实现的。在Spring Boot项目中，使用Knife4j需要添加依赖： ​ 然后，需要添加配置，则在项目的包下创建类：​ 完成后启动项目，从浏览器进入localhost：8080.doc.html#/home即可进入 ​ 注意：必须修改以上配置中的包名，保证是当前项目中控制器类所在的包！其它各项均可不修改，以上配置代码可以从Knife4j的官网找到！最后，还需要在配置文件中开启Knife4j的增强模式： 完成后，启动项目，在浏览
swagger2(knife4j) 注解说明
leaf__yang的博客
08-11 3690
swagger2(knife4j) 注解说明
Knife4j使用教程
jakelihua
08-28 2345
查看和测试接口：在Knife4j的文档页面上，你可以查看和测试你的API接口。可以通过分类、搜索等方式快速定位到需要的接口，点击接口可以查看详细的接口信息和示例。集成Swagger：Knife4j基于Swagger，可以直接解析Swagger注解生成API文档，无需额外的配置和编写文档。配置Swagger注解：在你的API接口类和方法上添加Swagger注解，用于描述接口的信息、参数、返回值等。引入依赖：在你的项目中添加Knife4j的相关依赖，具体的依赖配置可以参考Knife4j的官方文档。
Knife4j使用教程（四） -- Controller类的配置注解
PUYALEI的博客
10-27 543
添加在处理请求的方法的参数上，当某个参数不需要显示在API文档中，则需要在参数上添加此注解。添加在处理请求的方法上，swagger文档则不生成该方法的API文档。用于对@ApiOperation进行更详细的配置和。用于方法，参数，字段说明 表示对参数的要求和说明。用于方法，表示一个http请求访问该方法的操作。
Spring Boot 3和Knife4j的最佳实践 注解对照信息
BananaNo2的博客
08-01 1390
在这篇文章中，我们详细介绍了如何在Spring Boot 3项目中整合Knife4j以增强API文档的生成和展示。通过一个具体的项目示例，逐步展示了如何配置pom文件、引入Knife4j依赖、以及在application.yml文件中进行必要的配置。我们还提供了自定义配置的代码示例，展示了如何使用Knife4j配置多个模块和首页描述信息。此外，文章还包含了页面展示信息的截图，方便读者理解最终效果。最后，我们列出了Swagger 2与OpenAPI 3注解的对应关系，帮助开发者快速上手Knife4j。
Knife4j使用教程（二） -- 配置Swagger相关信息
PUYALEI的博客
10-27 350
Knife4j使用教程（二） -- 配置Swagger相关信息
Knife4j 使用教程
liutianxiazhendehao的博客
10-26 1万+
前言： knife4j继承了swagger的众多优点，并进行发展，可以看做是swagger的升级版，以下是knife4j的使用步骤 1.第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下： <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId>
knife4j使用教程
qq_33266327的博客
06-08 541
【代码】knife4j使用教程。
Knife4j--使用教程
古月的博客
08-31 3113
wu
Knife4j常用注解
geimogo_的博客
04-22 5010
帮你少走半个月弯路确定不进来看看！
Knife4j-的使用(详细教程)
热门推荐
xhmico的博客
07-17 2万+
之前有写过swagger怎么使用的教程，但是现在很多项目用的接口文档其实是Knife4jKnife4j它是对swagger在线接口文档的一个增强，按照官网的话说就是给swagger做了一个更好看皮肤的同时加了一些新的功能，本章内容我会向大家介绍在项目中如整合knife4j以及一些使用的细节。Swagger-的使用(详细教程)如果你之前没有接使用过swagger的话，建议先看下上篇博客。关于Knife4j的介绍官方文档其实解释得很清楚了，我就简单 copy 一下了。Knife4j的前身是，前身是一个纯。
Knife4j使用
小林的博客
06-05 933
Knife4j是一个用于生成和展示API文档的工具，同时它还提供了在线调试的功能，可以看作是Swagger的升级版，界面也比Swagger更好看，下图是其工作界面。
Knife4j注解说明
weixin_45131680的博客
07-05 1271
【代码】Knife4j注解说明。
knife4j注解实体
01-25
### Knife4j 注解实体及其使用方法 #### 1. `@ApiOperation` 注解 此注解主要用于描述控制器的方法功能。通过该注解可以清晰地表达API的具体用途以及操作对象。 ```java @Api(tags = "用户管理") @RestController @RequestMapping("/users") public class UserController { @ApiOperation(value = "获取指定ID的用户详情", notes = "根据用户ID查询并返回用户的详细信息") @GetMapping("/{id}") public User getUserById(@PathVariable Long id) { // 方法实现... return userService.getUserById(id); } } ``` 上述代码片段展示了如何应用 `@ApiOperation` 来标注一个GET请求处理函数，其中指定了value属性来解释这个接口的作用[^2]。 #### 2. `@ApiParam` 注解 当需要对某个特定参数进行更详细的说明时，则可采用 `@ApiParam` 。它能够帮助开发者更好地理解输入参数的意义。 ```java @PostMapping("/createUser") public ResponseEntity<String> createUser( @ApiParam(name = "username", value = "用户名字串", required = true, example = "JohnDoe") @RequestParam String username, @ApiParam(name = "age", value = "年龄数值", allowableValues = "range[0,150]") @RequestParam Integer age){ // 创建用户的业务逻辑... return new ResponseEntity<>("Success", HttpStatus.CREATED); } ``` 这里不仅定义了两个必填项——用户名和年龄，还设定了它们各自的取值范围或示例数据[^4]。 #### 3. `@ApiModel` 和 `@ApiModelProperty` 注解组合 对于复杂的数据结构如DTO类来说，可以通过这两个注解共同作用于模型字段之上，从而提供更加详尽的信息给前端开发人员或其他使用者参考。 ```java @ApiModel(description="员工实体类") class Employee{ private static final long serialVersionUID = 1L; @ApiModelProperty(notes = "员工编号", name = "empNo", dataType = "Long", example = "789456123") private Long empNo; @ApiModelProperty(notes = "姓名", name = "name", required = true) private String name; // getter setter methods omitted } ``` 这段代码中，`@ApiModel` 描述了一个名为“员工”的实体；而其内部成员变量则由对应的 `@ApiModelProperty` 进一步细化说明各个属性的特点。 ---
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值