Swagger注解概览

Swagger是什么

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈,能够管理API的整个生命周期,从设计、文档到测试与部署。

Swagger重要特性

  • 代码侵入式注解
  • 遵循YAML文档格式
  • 非常适合三端(PC、iOS及Android)的API管理,尤其适合前后端完全分离的架构模式。
  • 减少没有必要的文档,符合敏捷开发理念
  • 功能强大

Swagger开源实现

  1. Swagger UI,基于Swagger-compliant API的一套可以展示优美文档的Web应用。
  2. Swagger Editor,一款以YAML格式编辑与管理API的工具,同时支持JSON格式的文档描述。
  3. Swagger-Core,Swagger的Java/Scala实现,并已集成 JAX-RS (Jersey, Resteasy, CXF…), Servlets与Play Framework。
  4. Swagger-JS,Swagger的Javascript版本实现。
  5. 更多

Swagger注解

注解 说明
Api 用在类上,说明该类的作用
ApiModel 描述一个Model的信息,使用@RequestBody的场景
ApiModelProperty 描述一个Model的属性
ApiOperation 用在方法上,说明方法的作用
ApiParam 请求属性
ApiResponse 用在@ApiResponses中,一般用于表达一个错误的响应配置
ApiResponses 用于表示一组响应集配置
ResponseHeader 响应头设置
ApiImplicitParams 用在方法上包含一组参数说明
ApiImplicitParam 用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

Swagger注解属性

属性 说明
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, “application/json, application/xml”
consumes For example, “application/json, application/xml”
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
response 返回的对象,默认响应类 Void
responseContainer 这些对象是有效的 “List”, “Set” or “Map”.,其他无效
httpMethod “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code http的状态码 默认 200
message 状态码对应的响应信息
extensions 扩展属性
name 属性名称
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
example 举例子
reference 参考ApiOperation中配置
responseHeaders 参考 ResponseHeader 属性配置说明
description 头描述
paramType 参数放在哪个地方
dataType 参数类型,有String/int,无用

参考文档

swagger常用注解说明
Swagger Annotation 详解(建议收藏)