Swagger的描述注释配置详解

清单 6. 给 Controller 添加描述信息

@Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")
public class UserController

@Api: 可设置对控制器的描述。

表 1. @Api 主要属性

注解属性 类型 描述
tags String[] 控制器标签。
description String 控制器描述(该字段被申明为过期)。
二、通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述,当然这个注解还可以指定很多内容,我们在下面的相关注解说明章节中详细解释。

清单 7. 给接口添加描述信息

@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {return false;
}

@ApiOperation: 可设置对接口的描述。
表 2. @ApiOperation 主要属性

注解属性 类型 描述
value String 接口说明。
notes String 接口发布说明。
tags Stirng[] 标签。
response Class<?> 接口返回类型。
httpMethod String 接口请求方式。
@ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
@ApiImplicitParams: 用于描述接口的非对象参数集。
@ApiImplicitParam: 用于描述接口的非对象参数,一般与 @ApiImplicitParams 组合使用。
表 3. @ApiImplicitParam 主要属性

注解属性 描述
paramType 查询参数类型,实际上就是参数放在那里。取值:
path:以地址的形式提交数据,根据 id 查询用户的接口就是这种形式传参。
query:Query string 的方式传参。
header:以流的形式提交。
form:以 Form 表单的形式提交。
dataType 参数的数据类型。取值:
Long
String
name 参数名字。
value 参数意义的描述。
required 是否必填。取值:
true:必填参数。
false:非必填参数。
三、实体描述,我们可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

清单 8. 给实体类添加描述信息

@ApiModel("用户实体")
public class User {@ApiModelProperty("用户 id")
private int id;
}

@ApiModel: 可设置接口相关实体的描述。
@ApiModelProperty: 可设置实体属性的相关描述。
表 4. @ApiModelProperty 主要属性

注解属性 类型 描述
value String 字段说明。
name String 重写字段名称。
dataType Stirng 重写字段类型。
required boolean 是否必填。
example Stirng 举例说明。
hidden boolean 是否在文档中隐藏该字段。
allowEmptyValue boolean 是否允许为空。
allowableValues String 该字段允许的值,当我们 API 的某个参数为枚举类型时,使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。
四、文档信息配置,Swagger 还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息,但与上面几条不同的是这些信息不是通过注解配置,而是通过创建一个 ApiInfo 对象,并且使用 Docket.appInfo() 方法来设置,我们在 SwaggerConfig.java 类中新增如下内容即可。

清单 9. 配置文档信息

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo("Spring Boot 项目集成 Swagger 实例文档","我的博客网站:https://itweknow.cn,欢迎大家访问。","API V1.0","Terms of service",new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"),"Apache", "http://www.apache.org/", Collections.emptyList());
}

四、过滤不需要扫描的包:

有些时候我们并不是希望所有的 Rest API 都呈现在文档上,这种情况下 Swagger2 提供给我们了两种方式配置,一种是基于 @ApiIgnore 注解,另一种是在 Docket 上增加筛选。

@ApiIgnore 注解。
如果想在文档中屏蔽掉删除用户的接口(user/delete),那么只需要在删除用户的方法上加上 @ApiIgnore 即可。

清单 10. @ApiIgnore 使用实例

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths()两 个方法来帮助我们在不同级别上过滤接口:
apis():这种方式我们可以通过指定包名的方式,让 Swagger 只去某些包下面扫描。
paths():这种方式可以通过筛选 API 的 url 来进行过滤。
在集成 Swagger2 的章节中我们这两个方法指定的都是扫描所有,没有指定任何过滤条件。如果我们在我们修改之前定义的 Docket 对象的 apis() 方法和 paths() 方法为下面的内容,那么接口文档将只会展示 /user/add 和 /user/find/{id} 两个接口。

清单 11. 使用 Docket 配置接口筛选

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),PathSelectors.ant("/user/find/*")))

五、自定义响应消息

Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息,但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息,假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息,我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容:

清单 12. 自定义响应消息

.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder().code(500).message("服务器发生异常").responseModel(new ModelRef("Error")).build(),new ResponseMessageBuilder().code(403).message("资源不可用").build()
));

添加如上面的代码后,如下图所示,您会发现在 SwaggerUI 页面展示的所有 GET 类型请求的 403 以及 500 错误的响应消息都变成了我们自定义的内容。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/522420.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

当你和天猫精灵对话时,它在想什么?阿里智能对话技术深度解读

摘要&#xff1a; 术语对齐 TaskBot引擎&#xff1a; 核心处理对象是“技能”&#xff0c;我们把技能定义成结构化(querycontent)、垂直场景化的任务&#xff0c;比如实时场景查询、工具类、控制类等QABot引擎&#xff1a;包括KG-QA引擎、QAPair引擎、DeepQA引擎。术语对齐Task…

训练softmax分类器实例_知识蒸馏:如何用一个神经网络训练另一个神经网络

公众号关注 “ML_NLP”设为 “星标”&#xff0c;重磅干货&#xff0c;第一时间送达&#xff01;转载自&#xff1a;AI公园作者&#xff1a;Tivadar Danka编译&#xff1a;ronghuaiyang导读知识蒸馏的简单介绍&#xff0c;让大家了解知识蒸馏背后的直觉。如果你曾经用神经网络来…

10个业界最流行的Kubernetes发行版

戳蓝字“CSDN云计算”关注我们哦&#xff01;作者 | Serdar来源 | RancherLabs如果你需要大规模的容器编排&#xff0c;想必Kubernetes毋庸置疑是你的首要选择&#xff0c;这一由谷歌推出的开源容器编排系统近年来发展飞速&#xff0c;大受业界及广大用户好评。尽管如此&#x…

神经进化是深度学习的未来

摘要&#xff1a; 本文主要讲了神经进化是深度学习的未来&#xff0c;以及如何用进化计算方法&#xff08;EC&#xff09;优化深度学习&#xff08;DL&#xff09;。过去几年时间里&#xff0c;我们有一个完整的团队致力于人工智能研究和实验。该团队专注于开发新的进化计算方法…

通用mapper 如何处理多表条件查询通过list封装(一对多)

实现原理 通用mapper本身的接口方法&#xff0c;默认适用于单表处理&#xff0c;所以多表处理必须去定义xml和专用的pojo类以及mapper接口。为了实现多表关联查询 把调试好的的多表关联查询多表的SQL&#xff0c;复制到在xml中&#xff0c;把参数替换为动态的占位符&#xff0c…

dell服务器怎么看硬件状态,从DELL 2950和DELL R710看服务器硬件

一、CPU1、x86是采用cisc(Complex Instrution Set Computer)架构的处理器&#xff0c;是Intel首先开发制造的一种微处理器体系结构的泛称。X86架构的CPU是目前常用的CPU。2、CPU厂商(Intel、AMD等)及CPU类型(intel cpu系统型号、amd cpu系列型号)。3、Dell R2950支持Intel Xeon…

深度学习的关键术语

摘要&#xff1a; 本文着重介绍了深度学习的一些关键术语&#xff0c;其中包括生物神经元&#xff0c;多层感知器&#xff08;MLP&#xff09;&#xff0c;前馈神经网络和递归神经网络。对于初学者来说&#xff0c;掌握它们可以防止在学习请教时的尴尬~深度学习已经成为编程界的…

虚拟化精华问答 | 虚拟化技术分类

虚拟化是一种资源管理技术, 是将计算机的各种物理资源, 如服务器、网络、内存及存储等&#xff0c;予以抽象、转换后呈现出来&#xff0c;打破物理设备结构间的不可切割的障碍&#xff0c;使用户可以比原本的架构更好的方式来应用这些资源。这些资源的虚拟部分是不受现有资源的…

python标准库对象导入语句_Python标准库之Sys模块使用详解

sys 模块提供了许多函数和变量来处理 Python 运行时环境的不同部分. 处理命令行参数 在解释器启动后, argv 列表包含了传递给脚本的所有参数, 列表的第一个元素为脚本自身的名称. 使用sys模块获得脚本的参数 复制代码 代码如下: print "script name is", sys.argv[0]…

远程服务器 上传公钥,SecureCRT+Ubuntu SSH服务器的远程公钥登陆

有耐心地往下看&#xff0c;哥是实现了的&#xff0c;并且所有细节会给的相当的丰富哈。Ubuntu: Ubuntu 14.04 LTSopensshWindow10(64位):SecureCRT8.0看网上的列为同牛们说gitssh用&#xff0c;自己搭建git服务器&#xff0c;so嗨&#xff0c;所以行动起来&#xff0c;先给win…

通用mapper如何处理多表条件查询通过list封装(强烈不推荐)(一对一,一对多)

一、思路1:在service封装通过list的组合&#xff0c;强烈不建议&#xff0c;有性能问题&#xff0c;例如&#xff1a;Autowiredprivate StudentDao studentDao;Autowiredprivate Stu_labelDao stu_labelDao;Autowiredprivate CityDao cityDao;Autowiredprivate ClazzDao clazzD…

理解卷积神经网络的利器:9篇重要的深度学习论文(上)

摘要&#xff1a; 为了更好地帮助你理解卷积神经网络&#xff0c;在这里&#xff0c;我总结了计算机视觉和卷积神经网络领域内许多新的重要进步及有关论文。手把手教你理解卷积神经网络(一)手把手教你理解卷积神经网络(二)本文将介绍过去五年内发表的一些重要论文&#xff0c;并…

理解卷积神经网络的利器:9篇重要的深度学习论文(下)

摘要&#xff1a; 为了更好地帮助你理解卷积神经网络&#xff0c;在这里&#xff0c;我总结了计算机视觉和卷积神经网络领域内许多新的重要进步及有关论文。手把手教你理解卷积神经网络(一)手把手教你理解卷积神经网络(二)继“理解卷积神经网络的利器&#xff1a;9篇重要的深度…

工作流实战篇_01_flowable 流程Demo案例

由于群里有些朋友对这个flowable还不是 很熟悉&#xff0c;在群里的小伙伴的建议下&#xff0c;师傅(小学生05101)制作一个开源的项目源码&#xff0c;一共大家学习和交流&#xff0c;希望对有帮助&#xff0c;少走弯路 如果有不懂的问题可以入群&#xff1a;633168411 里面都是…

antd 进行ajax请求,react+dva+antd接口调用方式

一丶 安装通过 npm 安装 dva-cli 并确保版本是0.8.1或以上。$ npm install dva-cli -g$ dva -v0.8.1二丶创建新应用安装完dva-cli之后&#xff0c;就可以在命令行里访问到dva命令(不能访问&#xff1f;)。现在&#xff0c;你可以通过dva new创建新应用。$ dva new dva-quicksta…

基于MaxCompute的拉链表设计

摘要&#xff1a; 简单的拉链表设计 背景信息&#xff1a; 在数据仓库的数据模型设计过程中&#xff0c;经常会遇到这样的需求&#xff1a; 数据量比较大; 表中的部分字段会被update,如用户的地址&#xff0c;产品的描述信息&#xff0c;订单的状态、手机号码等等; 需要查看…

2019全球编程语言高薪排行榜登场;余承东正式宣布华为IFA2019 或发布麒麟990;OPPO、vivo和小米成立互传联盟…...

关注并标星星CSDN云计算极客头条&#xff1a;速递、最新、绝对有料。这里有企业新动、这里有业界要闻&#xff0c;打起十二分精神&#xff0c;紧跟fashion你可以的&#xff01;每周三次&#xff0c;打卡即read更快、更全了解泛云圈精彩newsgo go go 全新的索尼PS5&#xff08;图…

python文件输出log_Python同时向控制台和文件输出日志logging的方法

#-*- coding:utf-8 -*- import logging # 配置日志信息 logging.basicConfig(levellogging.DEBUG, format%(asctime)s %(name)-12s %(levelname)-8s %(message)s, datefmt%m-%d %H:%M, filenamemyapp.log, filemodew) # 定义一个Handler打印INFO及以上级别的日志到sys.stderr c…

MaxCompute使用常见问题总结

摘要&#xff1a; Maxcompute常见问题的总结&#xff0c;方便广大用户可以快速排查问题 计费相关 存储计费&#xff1a;按照存储在 MaxCompute 的数据的容量大小进行阶梯计费。 计算计费&#xff1a;MaxCompute 分按量后付费和按 CU 预付费两种计算计费方式。 按量后付费&#…

工作流实战_02_flowable 流程模板导入

由于群里有些朋友对这个flowable还不是很熟悉&#xff0c;在群里的小伙伴的建议下&#xff0c;师傅(小学生05101)制作一个开源的项目源码&#xff0c;一共大家学习和交流&#xff0c;希望对有帮助&#xff0c;少走弯路 如果有不懂的问题可以入群&#xff1a;633168411 里面都是…