简介:

为什么要用swagger，我的理由是方便，作为后端开放人员，最烦的事就是自己写接口文档和前端交互是不是需要各种参数很繁琐，项目集成swagger后就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。

优势:

1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便。
2.提供 Web 页面在线测试 API：有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

示例如图下:

swagger基本注解使用

注解及其使用如下(对应注解)：

注解	作用	使用位置
@Api	表示对类的说明常用参数	类上面
@ApiOperation	说明方法的用途、作用	方法上面
@ApiModel	表示一个返回响应数据的信息	响应类
@ApiModelProperty	描述响应类的属性	属性
@ApiIgnore	忽略某个字段使之不显示在文档中	属性

一、 @Api：用在请求的类上，表示对类的说明常用参数

参数	描述
tags	说明该类的作用，非空时将覆盖value的值
value	描述类的作用
description	对api资源的描述，在1.5版本后不再支持
basePath	基本路径可以不配置，在1.5版本后不再支持
position	如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
produces	设置MIME类型列表（output），例：“application/json, application/xml”，默认为空
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值
hidden	默认为false，配置为true 将在文档中隐藏

示例:

@CrossOrigin
@RestController
@RequestMapping("/customer/information")
@Api(tags = "定制橱柜~客户信息")
public class CrmCustomersController{}

接口文档示例:

二、@ApiOperation：用在请求的方法上，说明方法的用途、作用

参数	描述
value	说明方法的用途、作用
notes	方法的备注说明
tags	操作标签，非空时将覆盖value的值
response	响应类型（即返回对象）
responseContainer	声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”。
responseReference	指定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod	指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
responseHeaders	响应头列表
code	响应的HTTP状态代码。默认 200
hidden	默认为false，配置为true 将在文档中隐藏

示例:

    @ApiOperation(value = "供应商~导购(状态流转)")@RequestMapping(value = "queryStateExchange", method = RequestMethod.POST)public PmpResult queryStateExchange () int pageNum,String state){}

接口文档示例:

三、@ApiModelProperty:用在属性上，描述响应类的属性

参数	描述
value	此属性的简要说明。
name	允许覆盖属性名称
allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access	允许从API文档中过滤属性。
notes	目前尚未使用。
dataType	参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。
required	参数是否必传，默认为false
position	允许在类中对属性进行排序。默认为0
hidden	允许在Swagger模型定义中隐藏该属性。
example	属性的示例。
readOnly	将属性设置为只读
reference	指定对相应类型定义的引用，覆盖指定的任何参数值

示例:

接口文档示例:

四、 @ApiIgnore 忽略某个属性，使之不显示在swagger文档中显示

未加注解前示例:

加注解后示例:

    @ApiOperation(value = "客户列表")@RequestMapping(value = "customerlist", method = RequestMethod.GET)public PmpResult  queryCustomerList (@ApiIgnore @RequestParam(value="pageNum",defaultValue="1") int pageNum, @RequestParam(value="pageSize",defaultValue="10") int pageSize, String customersno, String customersname, String daogouid){}

加注解后接口文档示例:

五、@ApiImplicitParams 用法

示例:

    @ApiImplicitParams({ @ApiImplicitParam(value="客户编号(精确命中)",name="customersno",dataType="Stirng",paramType = "query"),@ApiImplicitParam(value="类型(04:门 05:口)",name="state",dataType="Stirng",paramType = "query"),@ApiImplicitParam(value="订单主表Uid",name="parentId",dataType="Stirng",paramType = "query")})@RequestMapping(value = "queryByDoorOrderlist", method = RequestMethod.POST)@ApiOperation(value = "基础项目~订单~木门")public PmpResult queryByDoorOrderlist(String customersno, String state,String parentId){}

接口文档示例: 显示描述信息

以上就是常用的注解示例，如需要其他注解可自行尝试。

swagger2 介绍+注解说明相关推荐

项目环境搭建，数据库，以及Swagger2介绍（二）
文章目录一.数据库设计二.数据库设计规约三.工程结构介绍四.创建父工程五.搭建service模块六.搭建service-edu模块七.讲师管理模块配置八.编写后台管理api接口九.讲 ...
传奇客户端文件介绍注解教程，GM必备知识
传奇客户端文件介绍注解教程,GM必备知识很多朋友架设微端,或者说修改传奇版本素材方面的内容的时候对于客户端很懵逼! 尤其是新手朋友他并不知道传奇客户端里面哪个文件是对应什么内容的! 今天我们将这些发 ...
Swagger2常用注解说明
文章目录 Swagger2简介使用Swagger解决的问题 Spring Boot集成Swagger2 添加依赖添加Swagger2Config配置类编写接口用户DTO 用户controlle ...
SpringBoot项目中使用Swagger2及注解解释（详细）
SpringBoot项目中使用Swagger2及注解解释这里写目录标题 SpringBoot项目中使用Swagger2及注解解释一.导入Swagger坐标依赖二.在spring启动类添加注解@E ...
SpringBoot+Swagger2常用注解
场景 SpringBoot+Swagger2实现可视化API文档流程: https://blog.csdn.net/BADAO_LIUMANG_QIZHI/article/details/936166 ...
详细介绍注解@ConfigurationProperties使用
文章目录一.@ConfigurationProperties介绍一.@ConfigurationProperties使用详情写在前面: 我是「境里婆娑」.我还是从前那个少年,没有一丝丝改变,时间 ...
Swagger2介绍及使用
项目中整合Swagger2 1.什么是swagger2 2.常用注解 3.项目中整合Swagger2 3.1.引入Swagger2依赖 3.2.编写swgger2配置类代码 3.3.在需要测试的模块中 ...
Swagger2介绍
前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接口变更后,能够及时准确地通 ...
SpringBoot集成Swagger2、Swagger2和Swagger3的区别Swagger的注解学习
Swagger的介绍 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新. 随着前后端 ...

swagger2 介绍+注解说明

swagger基本注解使用

五、@ApiImplicitParams 用法

swagger2 介绍+注解说明相关推荐

最新文章

热门文章