Swagger 3 已经发布了一段时间了，但是这里我们主要学习目前更主流的 Swagger 2。

Swagger 2 整体注解

Swagger 2 请求类注解，主要用于 Controller 类上
Swagger 2 请求方法注解，主要用于 Controller 类对应的方法上
Swagger 2 对象类注解，主要用于 JavaBean 上

1、Swagger 2 请求类注解

@Api 标识 Swagger 识别的类
@Api 放在 @Controller 注解并列的请求类上
核心参数包含 value、tags、description

@Api()：用在请求的类上，表示对类的说明，也代表了这个类是 swagger2 的资源，参数：

tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。
value - 字段说明
description - 注释说明这个类

2、Swagger 2 请求方法注解

@ApiOperation 标识 Swagger 识别的方法
@ApiImplicitParam 标识方法的参数的说明
@ApiResponse 标识方法返回值的说明

@ApiOperation 注解常用属性：

value：对该操作进行简单的描述，尽量控制在120字符以内。
notes：对操作的详细描述。
httpMethod：指定操作使用的HTTP方法类型，可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。
tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。实例代码：

@ApiImplicitParam 注解常用属性：

name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

@ApiResponse 注解常用属性：

code：数字，例如400
message：信息，例如"请求参数不正确"
response：抛出异常的类

3、Swagger 2 对象类注解

@ApiModel 标识 Swagger 识别的 JavaBean
@ApiModel 放在 JavaBean 的类定义上
@ApiModelProperty 标识 JavaBean 属性

@ApiModel 注解常用属性：

value：为模型提供备用名称
description：提供详细的类描述
parent：为模型提供父类以允许描述继承关系
discriminatory：支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes：从此模型继承的子类型数组
reference：指定对应类型定义的引用，覆盖指定的任何其他元数据

@ApiModelProperty 注解常用属性：

value：属性简要说明
name：运行覆盖属性的名称。重写属性名称
allowableValues：作用为限制此参数存储的长度
access：作用为允许从API文档中过滤属性
notes：作用为该字段的注释说明
dataType：作用为参数的数据类型
required：作用为指定参数是否可以为空，默认为false
position：作用为允许显式地对模型中的属性排序
hidden：作用为是否允许模型属性隐藏在Swagger模型定义中，默认为false
example：作用为属性的示例值
readOnly：作用为是否允许将属性指定为只读，默认为false
reference：作用为指定对对应类型定义的引用，重写指定的任何其他数据名称
allowEmptyValue：作用为是否允许传递空值，默认为false

4、总结

【Swagger】Swagger 注解学习相关推荐

SpringBoot集成Swagger2、Swagger2和Swagger3的区别Swagger的注解学习
Swagger的介绍 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新. 随着前后端 ...
Spring Boot 1.5.8集成Swagger2 + YApi —— Swagger常用注解说明
前言受新型冠状病毒的影响,在家像猪一样不是睡就是吃,闲着就学着用下Swagger和YApi,特将这几天的学习成果写成了这系列的文章,希望能对大家有所帮助.武汉加油,中国加油! Spring Boot ...
简谈swagger的注解说明
swagger通过注解表明该接口会生成文档,包括接口名.请求方法.参数.返回信息的等等.• @Api:修饰整个类,描述Controller的作用• @ApiOperation:描述一个类的一个方法,或 ...
swagger 返回json字符串_[Swagger] Swagger Codegen 高效开发客户端对接服务端代码
[Swagger] Swagger Codegen 高效开发客户端对接服务端代码 @TOC 手机用户请横屏获取最佳阅读体验,REFERENCES中是本文参考的链接,如需要链接和更多资源,可以关注其他博 ...
Spring 注解学习手札（七）补遗——@ResponseBody，@RequestBody，@PathVariable(转)
最近需要做些接口服务,服务协议定为JSON,为了整合在Spring中,一开始确实费了很大的劲,经朋友提醒才发现,SpringMVC已经强悍到如此地步,佩服! 相关参考: Spring 注解学习手札( ...
@data注解的作用_Java中注解学习系列教程-2
在上一篇文章中,我们讲解了:Java中注解的定义.JDK中内置注解.第三方注解. 本文是注解系列教程中的第二篇.来看看今天主要内容: 1:注解的分类 2:元注解说明 3:自定义注解声明一:注解的 ...
java自定义注解学习笔记
注解学习笔记之自定义注解 @Target({1,2,3,4,5,6,7}) 1.ElementType.CONSTRUCTOR:用于描述构造器 2.ElementType.FIELD:用于描述域 3. ...
@excel 注解_Java中注解学习系列教程-3
本文是<Java中注解学习系列教程>第三篇文章在前两篇中我们学习了注解的定义.JDK内置注解.注解分类及自定义注解的写法. 本文咱们将学习: 1:自定义注解一些说明 2:自定义注解怎 ...
Java注解学习一：注解术语
2019独角兽企业重金招聘Python工程师标准>>> 一.元注解 @Target:表示该注解可以用于什么地方.可选的ElementType参数包括: TYPE:类,接口(包括注解类 ...
excel导出多重表头utils_Java中注解学习系列教程-4 使用自定义注解实现excel导出...
本文是<Java中注解学习系列教程>第四篇文章也是小案例文章. 自定义注解小案例是:使用自定义注解实现excel导出. Excel导出分析: 有表头.数据值.一般第一行是表头,从第二行 ...

【Swagger】Swagger 注解学习