Swagger常用注解

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

Swagger主要有以下几个作用:

  • Swagger可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
  • Swagger文件可以在许多不同的平台上从代码注释中自动生成。
  • Swagger提供API在线测试功能
  • Swagger可以分析用户Swagger资源声明以各种语言生成客户端代码。

Swagger常用的功能还是生成在线API,接下来把Swagger常用的注解做以简单的记录。

  • @Api()用于类;

    表示标识这个类是swagger的资源

    1
    2
    3
    tags–表示说明 
    value–也是说明,可以使用tags替代
    但是tags如果有多个值,会生成多个list
  • @ApiOperation()用于方法;
    表示一个http请求的操作

    1
    2
    3
    value用于方法描述 
    notes用于提示内容
    tags可以重新分组(视情况而用)
  • @ApiParam()用于方法,参数,字段说明;
    表示对参数的添加元数据(说明或是否必填等)

    1
    2
    3
    name–参数名 
    value–参数说明
    required–是否必填
  • @ApiModel()用于类
    表示对类进行说明,用于参数用实体类接收

    1
    2
    value–表示对象名 
    description–描述
  • @ApiModelProperty()用于方法,字段
    表示对model属性的说明或者数据操作更改

    1
    2
    3
    4
    5
    6
    value–字段说明 
    name–重写属性名字
    dataType–重写属性类型
    required–是否必填
    example–举例说明
    hidden–隐藏
  • @ApiIgnore()用于类,方法,方法参数
    表示这个方法或者类被忽略,不被序列化

  • @ApiImplicitParam() 用于方法
    表示单独的请求参数

  • @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

    1
    2
    3
    4
    5
    name–参数ming 
    value–参数说明
    dataType–数据类型
    paramType–参数类型
    example–举例说明

推荐个大神的swagger-spring-boot-starter

1
2
3
4
5
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.1.RELEASE</version>
</dependency>

如果文章对你有帮助,欢迎点击上方按钮打赏作者