Swagger注解的使用

---

本文内容所使用的的Swagger版本：2.8.0

1. 启动Swagger注解

@EnableSwagger2

用在类上，启动Swagger。

2. 请求类方法描述注解

@ApiIgnore

用在类、方法、参数上，表示这个类或者方法被忽略（不需要swagger处理）。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String	""	简要说明忽略的原因

@Api

用在类上，对请求类进行描述。标识一个Controller类是Swagger文档类。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String	""	描述，无实际意义。
tags	String[]	""	分组
description	String	""	描述（已弃用）
basePath	String	""	基本路径（已弃用）已无效
position	int	0	显示顺序（已弃用）已无效
produces	String	int	输出数据内容类型（已弃用）已无效
consumes	String	int	输入数据内容类型（已弃用）已无效
protocols	String	int	请求协议
authorizations	Authorization[]	@Authorization(value = "")	高级特性认证时的配置
hidden	boolean	false	是否隐藏（不显示）

1. 注解属性value、tags二者的区别

   2. value属性作用在类和作用在方法上都用于描述；

   3. tags属性作用在类和作用在方法上都用于分组，但分组的效果区别很大：

      1. tags作用在类上时，会对全局的方法分组，即根据tags属性值复制多份，此时方法上的tags值无效，方法上tags配或不配效果都一样。

      2. tags作用在方法上时，会根据当前类的所有方法的tags值做分组，粒度更细。

属性包含的注解

• @Authorization

使用方法

@RestController
@RequestMapping(value = "swaggerTest")
@Api(tags = "Swagger测试相关接口",description = "Swagger测试相关接口的描述")
public class SwaggerTestController {

}

@ApiOperation

用在方法上，对请求方法进行描述。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String		描述
notes	String	""	详细描述
tags	String[]	""	分组
response	Class	Void.class	响应参数类型
responseContainer	String	""	该属性对这些对象是有效的：List、Set、Map，其他无效。
responseReference	String	""	指定对响应类型的引用，本地/远程引用，并将覆盖任何其它指定的response()类
httpMethod	String	""	http请求方式，如：GET、HEAD、POST、PUT、DELETE、OPTION、SPATCH
position	int	0	显示顺序（已弃用）已无效
nickname	String	""	第三方工具使用operationId来唯一表示此操作
produces	String	""	输出数据内容类型，如：application/json,application/xml（多个用英文逗号隔开）
consumes	String	""	输入数据内容类型，如：application/json,application/xml（多个用英文逗号隔开）
protocols	String	""	请求协议
authorizations	Authorization[]	@Authorization(value = "")	高级特性认证时的配置
hidden	boolean	false	是否隐藏（不显示）
responseHeaders	ResponseHeader[]	@ResponseHeader(name = "", response = Void.class)	响应头信息，@ResponseHeader数组
code	int	200	http的状态码
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = "", value = "")	扩展属性

属性包含的注解

• @Authorization
• @ResponseHeader
• @Extension

使用方法

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

3. 请求参数描述注解

@ApiImplicitParams

常用在方法上，对请求参数列表进行描述。
其中的value属性可包含多个@ApiImplicitParam，对每个参加进行具体的描述。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	ApiImplicitParam[]		参数列表描述

属性包含的注解

• @ApiImplicitParam

@ApiImplicitParam

用在方法上，对请求参数进行描述。当需要对多个参数进行描述时，作为@ApiImplicitParams的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String	""	参数名
value	String	""	参数说明
defaultValue	String	""	默认值
allowableValues	String	""	参数允许值
required	boolean	false	是否必填
access	String	""	参数过滤
allowMultiple	boolean	false	参数是否可以通过多次出现来接受多个值，默认不允许
dataType	String	""	参数的数据类型，可以使类名或原始数据类型
dataTypeClass	Class	Void.class	参数的数据类型，如果提供则覆盖 dataType
paramType	String	""	参数类型，有效值为 path, query, body, header, form
example	String	""	非body类型的参数示例
examples	Example	@Example(value = @ExampleProperty(mediaType = “”, value = “”))	body类型的参数示例
type	String	""	添加覆盖检测到的类型的功能
format	String	""	添加提供自定义format格式的功能
allowEmptyValue	boolean	false	添加将格式设置为空的功能
readOnly	boolean	false	添加被指定为只读的功能
collectionFormat	String	""	添加使用array类型覆盖collectionFormat的功能

属性包含的注解

• @Example

属性paramType取值

• header ：通过@RequestHeader获取
• query：通过@RequestParam获取
• path：通过@PathVariable获取
• body：通过@RequestBody获取
• form：通过@RequestParam获取

使用方法

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),

    })
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

@ApiParam

用在方法、参数、类的字段上，对请求参数进行描述。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String	""	参数名
value	String	""	参数说明
defaultValue	String	""	默认值
allowableValues	String	""	参数允许值
required	boolean	false	是否必填
access	String	""	参数过滤
allowMultiple	boolean	false	参数是否可以通过多次出现来接受多个值，默认不允许
hidden	boolean	false	是否隐藏（不显示），默认false
example	String	""	非body类型的参数示例
examples	Example	@Example(value = @ExampleProperty(mediaType = "", value = ""))	body类型的参数示例
type	String	""	添加覆盖检测到的类型的功能
format	String	""	添加提供自定义format格式的功能
allowEmptyValue	boolean	false	添加将格式设置为空的功能
readOnly	boolean	false	添加被指定为只读的功能
collectionFormat	String	""	添加使用array类型覆盖collectionFormat的功能

属性包含的注解

• @Example

使用方法

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

4. 对象描述(请求响应)注解

@ApiModel

用在类上，对请求、响应类进行描述。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String	""	为提供模型的替代名称，默认情况下，使用类名
description	String	""	类的描述
parent	Class parent	Void.class	为模型提供父类以允许描述继承关系
discriminatory	String	""	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes	Class[]	{}	从此模型继承的子类型数组
reference	String	""	指定对应类型定义的引用，覆盖指定的任何其他元数据

@ApiModelProperty

常用在字段上，对请求、响应类的字段进行描述。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String	""	覆盖属性的名称
value	String	""	属性说明
allowableValues	String	""	参数允许值
access	String	""	过滤属性
notes	String	""	目前尚未使用
dataType	String	""	参数的数据类型，可以使类名或原始数据类型
required	boolean	false	是否必填
position	int	0	显示顺序
hidden	boolean	false	是否隐藏
example	String	""	属性的示例值
readOnly	boolean	false	添加被指定为只读的功能
reference	String	""	指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	boolean	false	允许传空值

使用方法

@Data
@ApiModel(description = "测试请求类")
public class TestReq {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名",example = "张三")
    private String userName;
    @ApiModelProperty(value = "性别：1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}

@Data
@ApiModel(description = "测试响应类")
public class TestRes {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "性别：1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}

5. 响应参数描述注解

@ApiResponses

用在方法、类上，对响应状态码列表进行描述。
注解的属性

属性名称	属性类型	属性默认值	属性描述
value	ApiResponse[]		响应状态码列表的描述

属性包含的注解

• @ApiResponse

@ApiResponse

用在方法上，对响应状态码进行描述。一般作为@ApiResponses的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
code	int		响应的HTTP状态码
message	String		响应的描述
response	Class	Void.class	用于描述消息有效负载的可选响应类，对应于响应消息对象的 schema 字段
reference	String	""	指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的response()类
responseHeaders	ResponseHeader[]	@ResponseHeader(name = "", response = Void.class)	可能响应的header列表
responseContainer	String	""	声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略

属性包含的注解

• @ResponseHeader

@ResponseHeader

用在方法上，对响应头信息进行描述。一般作为@ApiResponse的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String	""	响应头参数名称
description	String	""	响应头参数详细描述
response	Class	Void.class	响应头数据类型
responseContainer	String	""	声明包装响应的容器，有效值为List或Set，任何其他值都将被覆盖

使用方法

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
            @ApiResponse(code = 401, message = "没有权限"),
            @ApiResponse(code = 403, message = "禁止访问")
    })
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

6. 示例信息注解

@Example

用在注解类型上，用于描述示例属性列表信息。一般作为@ApiImplicitParam、@ApiParam的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	ExampleProperty[]		示例的属性信息集合

属性包含的注解

• @ExampleProperty

@ExampleProperty

用在注解类型上，用于描述示例属性信息。一般作为@Example的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
mediaType	String	“default”	属性名称
value	String		属性值

7. 扩展信息注解

@Extension

用在注解类型上，用于描述扩展选项信息。一般作为@ApiOperation、@Info、@Tag的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String	""	扩展的选项名称
properties	ExtensionProperty[]		扩展选项的属性集合

属性包含的注解

• @ExtensionProperty

@ExtensionProperty

用在注解类型上，用于描述扩展选项的属性信息。一般作为@Extension的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String		属性名称
value	String		属性值

8. Swagger配置相关注解

①、Swagger配置注解

@SwaggerDefinition

定义metadata level时使用，在Rest接口或类上使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
host	String	""	要在生成的Swagger定义中指定的主机
basePath	String	""	指定生成的Swagger文档定义basePath
consumes	String[]	""
produces	String[]	""
schemes	Scheme[]	Scheme.EFAULT	API 的传输协议
tags	Tag[]	@Tag(name = "")	可用于对单个Apis和ApiOperations的全局标记
securityDefinition	SecurityDefinition	@SecurityDefinition()	安全方案的定义
info	Info	@Info(title = "", version = "")	为swagger定义常规元数据
externalDocs	ExternalDocs	@ExternalDocs(url = "")	外部文档

属性包含的注解

• @Tag
• @ExternalDocs
• @Info
• @SecurityDefinition

②、标记信息注解

@Tag

用在注解类型上，用于对单个Apis和ApiOperations的全局标记。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String		标记的名称
description	String	""	标记的描述
externalDocs	ExternalDocs	@ExternalDocs(url = "")	标记的外部文档参考选项
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = "", value = "")	扩展属性集合选项

属性包含的注解

• @Extension

③、外部文档配置注解

@ExternalDocs

用在参数、方法、属性上，使用外部文档说明的时候使用。一般作为@SwaggerDefinition、@Tag的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String	""	目标文档的简要描述，GFM语法可用于富文本表示
url	String		引用文档的URL

④、元数据配置注解

@Info

用在注解类型上，为swagger定义常规元数据。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
title	String		API的标题
version	String		API的版本
description	String	""	API的描述选项
termsOfService	String	""	API的可选服务条款
contact	Contact	@Contact(name = "")	API的可选联系信息
license	License	@License(name = "")	API的可选许可证信息
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = "", value = ""))	API的可选扩展列表信息

属性包含的注解

• @Contact
• @License
• @ExternalDocs

⑤、联系人配置注解

@Contact

用在注解类型上，配置API的可选联系信息。一般作为@Info的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String		联系人名称
url	String	""	联系人关联URL
email	String	""	联系人邮箱

⑥、许可证配置注解

@License

用在注解类型上，配置API的可选许可证信息。一般作为@Info的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String		许可证名称
url	String	""	许可证关联URL

⑦、安全方案配置注解

@Authorization

用在方法上，进行接口授权。一般作为@Api或@ApiOperation的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
value	String		要在此资源/操作上使用的授权方案名称。必须在资源列表的授权部分中定义名称
scopes	AuthorizationScope[]	@AuthorizationScope(scope = "", description = "")	授权方案为OAuth2时使用的范围

属性包含的注解

• @AuthorizationScope

@AuthorizationScope

用在方法上，描述接口授权范围。一般作为@Authorization的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
scope	String		要使用的OAuth2授权方案的范围。范围应事先在Swagger对象的securityDefinition部分中声明
description	String		在1.5.X中使用，保留用于旧版本的支持

@SecurityDefinition

用在注解类型上，用于安全方案的定义。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称	属性类型	属性默认值	属性描述
oAuth2Definitions	OAuth2Definition[]	{}	OAuth安全定义对象集合
apiKeyAuthDefintions	ApiKeyAuthDefinition[]	{}	已弃用
apiKeyAuthDefinitions	ApiKeyAuthDefinition[]	{}	API Key安全定义对象集合
basicAuthDefinions	BasicAuthDefinition[]	{}	已弃用
basicAuthDefinitions	BasicAuthDefinition[]	{}	基本身份验证安全定义对象集合

@ApiKeyAuthDefinition

OAuth安全定义对象。

注解的属性

属性名称	属性类型	属性默认值	属性描述
key	String		用于引用此安全定义的密钥
description	String	""	安全方案的简短描述
in	String	ApiKeyLocation	API 密钥的位置，有效值为query或header
name	String		要使用的query或header参数的名称

@BasicAuthDefinition

基本身份验证安全定义对象。

注解的属性

属性名称	属性类型	属性默认值	属性描述
key	String		用于引用此安全定义的密钥
description	String	""	安全方案的简短描述

@OAuth2Definition

OAuth安全定义对象。

注解的属性

属性名称	属性类型	属性默认值	属性描述
key	String		用于引用此安全定义的密钥
description	String	""	安全方案的简短描述
flow	Flow		OAuth2 安全方案使用的流程。有效值为implicit、password、application、accessCode
authorizationUrl	String	""	用于此流程的授权 URL。隐式和访问代码流需要
tokenUrl	String	""	用于此流程的令牌 URL。密码、应用程序和访问代码流需要
scopes	Scope[]	{}	作用范围集合

属性包含的注解

• @Scope

@Scope

注解的属性

属性名称	属性类型	属性默认值	属性描述
name	String		范围名称
description	String		范围描述

注解使用完整源码

SwaggerTestController

@RestController
@RequestMapping(value = "swaggerTest")
@Api(tags = "Swagger测试相关接口",description = "Swagger测试相关接口的描述")
// @ApiIgnore(value = "不想在Swagger文档上显示")
public class SwaggerTestController {

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),
    })
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
            @ApiResponse(code = 401, message = "没有权限", responseHeaders = {@ResponseHeader(name = "header2", description = "header2的描述",response = String.class)}),
            @ApiResponse(code = 403, message = "禁止访问")
    })
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

    @PostMapping("test3")
    @ApiOperation(value = "test3接口",notes = "test3接口详细描述")
    public ApiResult<TestRes> test3(@ApiParam(value = "请求类TestReq") @RequestBody TestReq req) {
        return ApiUtil.success(new TestRes());
    }
}

TestReq

@Data
@ApiModel(description = "测试请求类")
public class TestReq {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名",example = "张三")
    private String userName;
    @ApiModelProperty(value = "性别：1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}

TestRes

@Data
@ApiModel(description = "测试响应类")
public class TestRes {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "性别：1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}