文档首页 > > 常见问题> Java SDK问题> 如何使用Swagger注解?

如何使用Swagger注解?

分享
更新时间: 2019/09/11 GMT+08:00

概念阐述

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

场景描述

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

配置说明

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

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

  • @Api

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

    ServiceComb当前支持的属性只有tags。

    属性

    类型

    说明

    tags

    string

    设置当前Class下定义的operation的默认tag值。

  • @SwaggerDefinition

    作用于类级别,用于定义一个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两个属性。

  • @ApiOperation

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

    属性

    类型

    说明

    value

    string

    方法的简要说明,对应于Swagger契约operation的summary字段。

    notes

    string

    详细信息,对应于Swagger契约operation的description字段。

    tags

    string

    标注operation的标签。

    code

    int

    响应消息的HTTP状态码。

    response

    Class

    方法返回值类型。

    responseContainer

    string

    包装返回值的容器类型,可选值为List、Set、Map。

    responseHeaders

    @ResponseHeader

    响应消息的HTTP头,ServiceComb支持的属性值为name、response、responseContainer。

    consumes

    string

    指定请求体的数据格式。

    produces

    string

    指定响应体的数据格式。

    protocols

    string

    设置可用的协议(schemes),可选值有http、https、ws、wss,逗号分隔。

    httpMethod

    string

    设置HTTP方法

  • @ApiImplicitParam

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

    CSE Java SDK可以根据代码和SpringMVC、JAX-RS的注解自动推断出参数名称。如果@ApiImplicitParam配置的参数名称与自动推断的参数名不同,则则该注解配置的参数将被作为一个新的参数加入到注解所在的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官方文档。

  • @ApiImplicitParams

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

    属性

    类型

    说明

    value

    @ApiImplicitParam

    参数定义。

  • @ApiResponse

    用于描述返回消息的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。

  • @ApiResponses

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

    属性

    类型

    说明

    value

    @ApiResponse

    返回消息说明。

分享:

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区