使用 Swagger 注解

通过使用注解描述接口契约，用户可以利用ServiceComb的Swagger契约生成功能自动生成符合要求的契约文件，而无须手工编写和修改契约，能够有效提高开发效率。

关于Swagger注解的含义，可以在Swagger注解文档中找到官方说明。您可以对照该官方文档与本说明来了解如何在ServiceComb框架下使用注解指定Swagger契约的各项属性。

在ServiceComb中，Swagger注解不是必须使用的。当用户使用SpringMVC和JAX-RS的注解来标注微服务方法时，ServiceComb可以根据这些注解的值推断出各微服务方法的契约信息。

作用于类级别，用于定义一个Swagger资源中的信息。

属性	类型	说明
info.title	string	契约文件标题
info.description	string	描述信息
info.version	string	契约版本号
info.termsOfService	string	服务条款
info.contact	string	联系信息，包含name、email、url属性
info.license	string	许可证信息，包含name、url属性
info.extensions	string	扩展信息
consumes	string	接收的请求格式
produces	string	返回的应答格式
schemes	SwaggerDefinition.Scheme	可选值有`HTTP/HTTPS/WS/WSS/DEFAULT`
tags	`@Tag`	Tag定义，@Tag包含name、description、externalDocs三个属性
externalDocs	`@externalDocs`	外部说明文档链接，包含value、url两个属性

作用于方法级别，用于说明Swagger文档中operation的参数的属性。

属性	类型	说明
name	string	参数名称
value	string	参数说明
required	boolean	是否是必填参数
dataType	string	参数数据类型
paramType	string	参数位置，有效的可选值为path/query/body/header/form
allowableValues	string	参数的有效值范围
allowEmptyValue	boolean	是否允许空值
allowMultiple	boolean	是否允许多个值（若为true，则可以将参数作为数组）
collectionFormat	string	以何种格式指定参数数组，当前ServiceComb支持的值为`csv/multi`
defaultValue	string	参数默认值
example	string	一个非body参数的示例值
format	string	允许用户自定义数据格式，详情参见Swagger官方文档

用于描述返回消息的HTTP状态码所表达的含义。通常@ApiOperation可以表示一个正常情况返回消息的HTTP状态码，其他情形下的HTTP状态码由本注解描述。根据Swagger官方文档的描述，本注解不应该直接用于方法级别，而应该被包含在@ApiResponses中。

属性	类型	说明
code	int	返回消息的HTTP状态码
message	string	返回值的说明信息
response	Class<?>	返回值的类型
responseContainer	string	返回值的包装容器，可选值为`List/Set/Map`
responseHeaders	@ResponseHeader	描述一组返回消息的HTTP头，ServiceComb支持的`@ResponseHeader`的属性有`name`、`description`、`response`、`responseContainer`

使用Swagger注解