使用 Swagger 注解

概念阐述

Swagger提供了一套注解用于描述接口契约,用户使用注解,可以在代码中增加对于契约的描述信息。ServiceComb支持其中的部分注解。

场景描述

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

配置说明

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

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

@Api

@Api作用于类级别,在Swagger官方描述中是用于将一个Class标注为一个Swagger资源。但该注解在ServiceComb中不是必须的,ServiceComb可以根据@RestSchema@RpcSchema确定需要从哪些类中解析出Swagger契约。

属性类型说明
tagsstring设置当前Class下定义的operation的默认tag值
consumesstring指定契约级别的请求体数据格式,可以使用逗号分隔指定多个
producesstring指定契约级别的响应体数据格式,可以使用逗号分隔指定多个

@SwaggerDefinition

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

属性类型说明
info.titlestring契约文件标题
info.descriptionstring描述信息
info.versionstring契约版本号
info.termsOfServicestring服务条款
info.contactstring联系信息,包含name、email、url属性
info.licensestring许可证信息,包含name、url属性
info.extensionsstring扩展信息
consumesstring接收的请求格式
producesstring返回的应答格式
schemesSwaggerDefinition.Scheme可选值有HTTP/HTTPS/WS/WSS/DEFAULT
tags@TagTag定义,@Tag包含name、description、externalDocs三个属性
externalDocs@externalDocs外部说明文档链接,包含value、url两个属性

@ApiOperation

作用于方法级别,用于描述一个Swagger operation。

属性类型说明
valuestring方法的简要说明,对应于Swagger契约operation的summary字段
notesstring详细信息,对应于Swagger契约operation的description字段
tagsstring标注operation的标签
codeint响应消息的HTTP状态码
responseClass<?>方法返回值类型
responseContainerstring包装返回值的容器类型,可选值为ListSetMap
responseHeaders@ResponseHeader响应消息的HTTP头,ServiceComb支持的属性值为nameresponseresponseContainer
consumesstring指定请求体的数据格式
producesstring指定响应体的数据格式
protocolsstring设置可用的协议(schemes),可选值有httphttpswswss,逗号分隔
httpMethodstring设置HTTP方法
hiddenboolean是否隐藏此方法

@ApiImplicitParam

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

注意:ServiceComb可以根据代码和SpringMVC、JAX-RS的注解自动推断出参数名称。如果@ApiImplicitParam配置的参数名称与自动推断的参数名不同,则则该注解配置的参数将被作为一个新的参数加入到注解所在的operation中;否则将覆盖同名参数的属性。

属性类型说明
namestring参数名称
valuestring参数说明
requiredboolean是否是必填参数
dataTypestring参数数据类型
paramTypestring参数位置,有效的可选值为path/query/body/header/form
allowableValuesstring参数的有效值范围
allowEmptyValueboolean是否允许空值
allowMultipleboolean是否允许多个值(若为true,则可以将参数作为数组)
collectionFormatstring以何种格式指定参数数组,当前ServiceComb支持的值为csv/multi
defaultValuestring参数默认值
examplestring一个非body参数的示例值
formatstring允许用户自定义数据格式,详情参见Swagger官方文档

@ApiImplicitParams

@ApiImplicitParams作用于方法、类级别,用于批量指定多个@ApiImplicitParam

属性类型说明
value@ApiImplicitParam参数定义

@ApiResponse

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

属性类型说明
codeint返回消息的HTTP状态码
messagestring返回值的说明信息
responseClass<?>返回值的类型
responseContainerstring返回值的包装容器,可选值为List/Set/Map
responseHeaders@ResponseHeader描述一组返回消息的HTTP头,ServiceComb支持的@ResponseHeader的属性有namedescriptionresponseresponseContainer

@ApiResponses

作用于方法、类级别,用于指定和说明一组返回值。

属性类型说明
value@ApiResponse返回消息说明