Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使文档成为项目的一部分,使文档与代码保持同步。为了达到这个目标,Swagger 允许开发者通过注解(Annotation)的方式来定义接口的相关信息。
以下是一些在使用 Swagger 构建 API 文档时常用的注解:
@Api
用于类;表示标识这个类是 swagger 的资源。
- tags:用于说明该类的作用。
- value:也是说明,但通常用这个指定路径。
@ApiOperation
用于方法;表示一个 HTTP 请求的操作。
- value:用于方法描述。
- notes:用于提供该 API 的额外说明,支持 Markdown。
@ApiParam
用于方法的参数;表示对参数的添加元数据(说明或是否必填等)。
- name:参数名。
- value:参数说明。
- required:是否必须。
@ApiModel
用于类;表示对类进行说明,用于参数用实体类接收。
- value:描述。
- description:更详细的描述。
@ApiModelProperty
用于类的属性;表示对 model 属性的说明或者数据操作更改。
- value:属性说明。
- required:是否必须。
- exa