Swagger

  • 号称世界上最流行的Api框架
  • RestFul Api 文档在线自动生成工具 => Api 文档与Api定义同步更新
  • 直接运行，可以在线测试API接口
  • 支持多种语言（java、php、…）

Swagger 官网

在项目中使用Swagger需要 springfox

  • swagger2
  • ui

SpringBoot 集成Swagger

  1. 新建一个SpringBoot Web项目

  2. 导入相关依赖

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>

  3. 编写controller

  4. 配置swagger ==> Config

    @Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {}

  5. 运行项目，访问Swagger-ui页面 [http://localhost:8088/swagger-ui.html]

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-VrCetpiT-1587184802807)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200414115411769.png)]

  6. 配置 Swagger的基本信息

        /*** 配置Swagger的Docket的bean*/@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo());}private ApiInfo getApiInfo(){Contact contact = new Contact("jiongming.liao","https://yitu-inc.com","jiongming.liao@yitu-inc.com");return new ApiInfo("我的SwaggerAPI文档","Swagger Demo","v1.0","urn:tos",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}

  7. Swagger配置扫描接口

     /*** 配置Swagger的Docket的bean* enable: 是否开启Swagger*/@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo()).enable(true).select()//RequestHandlerSelectors 配置要扫描接口的方式//basePackage 配置要扫描的包//.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))//any(): 扫描全部//none(): 不扫描//withMethodAnnotation: 扫描方法上的注解
//                    .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))//withClassAnnotation: 扫描类上的注解.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//paths: 过滤路径.paths(paths()).paths(PathSelectors.ant("/VIID/**")).build();}private Predicate<String> paths() {return or(regex("/business.*"),regex("/some.*"),regex("/contacts.*"),regex("/pet.*"),regex("/springsRestController.*"),regex("/test.*"));}

  8. 配置API文档分组

    .groupName("A")

  9. 配置多个API文档分组

      @Beanpublic Docket docketA(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docketB(){return new Docket(DocumentationType.SWAGGER_2).groupName("B");}@Beanpublic Docket docketC(){return new Docket(DocumentationType.SWAGGER_2).groupName("C");}@Beanpublic Docket docketC(){return new Docket(DocumentationType.SWAGGER_2).groupName("D");}

    Swagger注释API

    API 作用范围 使用位置
    @ApiModel 描述返回对象的意义 用在返回对象类上
    @ApiModelProperty 对象属性 用在出入参数对象的字段上
    @Api 协议集描述 用于controller类上
    @ApiOperation 协议描述 用在controller的方法上
    @ApiResponses Response集 用在controller的方法上
    @ApiResponse Response 用在 @ApiResponses里边
    @ApiImplicitParams 非对象参数集 用在controller的方法上
    @ApiImplicitParam 非对象参数描述 用在@ApiImplicitParams的方法里边

@ApiModel

使用场景

​ 在实体类上边使用，标记类时swagger的解析类

属性

属性名称 数据类型 默认值 说明
value String 类名 为模型提供备用名称
description String “” 提供详细的类描述
parent Class<?> parent Void.class 为模型提供父类以允许描述继承关系
discriminatory String “” 支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes Class<?>[] {} 从此模型继承的子类型数组
reference String “” 指定对应类型定义的引用，覆盖指定的任何其他元数据

代码示例

@ApiModel(value = "响应结果集对象",description = "用于批量接口处理结果返回")

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Zge2J7tw-1587184802811)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200414193022211.png)]

@ApiModelProperty 对象属性

使用场景

​ 使用在被 @ApiModel 注解的模型类的属性上

属性

属性名称 数据类型 默认值 说明
value String “” 属性简要说明
name String “” 运行覆盖属性的名称。重写属性名称
allowableValues String “” 限制参数可接收的值，三种方法，固定取值，固定范围
access String “” 过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter
notes String “” 目前尚未使用
dataType String “” 参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型
required boolean false 是否为必传参数,false:非必传参数; true:必传参数
position int 0 允许在模型中显示排序属性
hidden boolean false 隐藏模型属性，false:不隐藏; true:隐藏
example String “” 属性的示例值
readOnly boolean false 指定模型属性为只读，false:非只读; true:只读
reference String “” 指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue boolean false 允许传空值，false:不允许传空值; true:允许传空值

代码示例

    @ApiModelProperty(name = "requestURL", value = "请求URL",notes = "请求URL", required = true)private String requestURL;@ApiModelProperty(value = "状态码",notes = "处理结果状态码", required = true)private String statusCode;@ApiModelProperty(value = "状态描述",notes = "处理结果描述", required = true)private String statusString;@ApiModelProperty(value = "跟踪ID", notes = "跟踪ID", required = true)private String id;@ApiModelProperty(value = "本地时间", notes = "本地时间", required = true)private String localTime;

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-VXZuPGkg-1587184802814)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200414193333600.png)]

@Api 协议集描述

使用场景

​ 在controller类上使用

属性

属性名称 数据类型 默认值 说明
tags String[] {""} 表示说明
value String “” 也表示说明，与tags同时存在时取tags的值
description String “” 注释说明这个类（过时）
basePath String “”
position String “”
produces String “” 采用逗号分隔的 content types 类型的返回数据，例如:application/json,application/xml
consumes String “” 采用逗号分隔的 content types 类型的入参数据类型，例如:application/json,application/xml
protocols String “” 指定协议类型:http,https,ws,wss,多个协议使用逗号进行分隔
Authorization Authorization[] @Authorization("") 获取此操作的授权列表

代码示例

@Api(tags = {"设备管理接口"})
@RestController
@RequestMapping(value = "/VIID/APEs")
public class ApeController {}

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-h894JxMV-1587184802818)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200417143022592.png)]

@ApiOperation协议描述

使用场景

​ 用在controller的方法上

属性

属性名称 数据类型 默认值 说明
value String 接口简要说明，120字符或更少
notes String “” 接口详细描述
tags String[] “” tag 列表，可用于按自愿或任何其它限定符对操作进行逻辑分组
response Class<?> Void.class 接口返回类型
responseContainer String “” 声明包装响应的容器。有效值为 List,Set,Map，任何其它值都将被忽略
responseReference String “” 指定对响应类型的引用，本地/远程引用，并将覆盖任何其它指定的response()类
httpMethod String “” 请求方式:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”,如果未指定则使用除"PATH"之外的其它所有
nickname String “” 第三方工具使用operationId来唯一表示此操作
produces String “” 采用逗号分隔的 content types 类型的返回数据，例如:application/json,application/xml
consumes String “” 采用逗号分隔的 content types 类型的入参数据类型，例如:application/json,application/xml
protocols String “” 指定协议类型:http,https,ws,wss,多个协议使用逗号进行分隔
authorizations Authorization[] @Authorization(value = “”) 获取此操作的授权列表
hidden boolean false 是否隐藏操作列表中的操作
responseHeaders ResponseHeader[] @ResponseHeader(name = “”, response = Void.class) 指定 response header 信息列表
code int 200 HTTP返回状态码
extensions Extension[] @Extension(properties = @ExtensionProperty(name = “”, value = “”)) 可选的扩展数组

代码示例

 @ApiOperation(value = "批量创建采集设备", notes = "根据上传的信息创建采集设备")public ResponseStatusList createApes(HttpServletRequest request,@RequestBody @ApiParam(value = "采集设备创建对象列表", required = true) APEList apeList) {String url = request.getRequestURL().toString();ResponseStatusList responseStatusList = new ResponseStatusList();responseStatusList.setResponseStatusObject(new ArrayList<>());apeList.getAPEObject().forEach(ape -> {responseStatusList.getResponseStatusObject().add(ResponseStatusFactory.getResponseStatus(url, ape.getApeID()));});return responseStatusList;}

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-zAQdDdAp-1587184802820)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200417144131274.png)]

@ApiResponses

使用场景

​ 在 Rest 接口上使用，用作返回值的描述

属性

属性名称 数据类型 默认值 说明
value ApiResponse[] ApiResponse 列表

@ApiResponse

使用场景

​ 在 Rest 接口或类上和 @ApiResponses 组合使用，组装返回参数说明

概述

描述操作的可能响应，这可用于描述 Rest API 调用中可能的成功和错误 code 码。此注解可以在方法或类级别应用；仅当在方法级别或抛出时未定义相同代码的@ApiResponse注解时才会解析类级别注解异常，如果响应中使用了不同的响应类，则可以通过将响应类于响应码组合使用。注意swagger不允许单个响应代码的多个响应类型。此注解不直接使用，单独使用时swagger不会解析，应该和ApiResponses组合使用。

属性

属性名称 数据类型 默认值 说明
code int 响应的HTTP状态码
message String 伴随响应的人类可读的消息
response Class<?> Void.class 用于描述消息有效负载的可选响应类，对应于响应消息对象的 schema 字段
reference String “” 指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的response()类
responseHeaders ResponseHeader[] @ResponseHeader(name = “”, response = Void.class) 可能响应的 header 列表
responseContainer String “” 声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略

代码示例

 @ApiOperation(value = "批量创建采集设备", notes = "根据上传的信息创建采集设备")@ApiResponses({@ApiResponse(code = 200, message = "成功"),@ApiResponse(code = 400, message = "错误的请求")})@RequestMapping(value = "", method = RequestMethod.POST)public ResponseStatusList createApes(HttpServletRequest request,@RequestBody @ApiParam(value = "采集设备创建对象列表", required = true) APEList apeList) {String url = request.getRequestURL().toString();ResponseStatusList responseStatusList = new ResponseStatusList();responseStatusList.setResponseStatusObject(new ArrayList<>());apeList.getAPEObject().forEach(ape -> {responseStatusList.getResponseStatusObject().add(ResponseStatusFactory.getResponseStatus(url, ape.getApeID()));});return responseStatusList;}

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-KCbsKBQA-1587184802821)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200417151003007.png)]

@ApiImplicitParams

使用场景

​ 用在请求的方法上，包含一组参数说明

属性

属性名称 数据类型 默认值 说明
@ApiImplicitParam ApiImplicitParam[] 用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息

@ApiImplicitParam

使用场景

​ 用在请求的方法上，包含一组参数说明

属性

属性名称 数据类型 默认值 说明
name String “” 参数名
value String “” 参数的汉字说明、解释
required 参数是否必须传
paramType 参数放在哪个地方·
header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType 参数类型
defaultValue 参数的默认值

代码示例

     @ApiOperation(value = "批量获取采集设备", notes = "根据上传的信息获取采集设备")@ApiImplicitParams({@ApiImplicitParam(name="name",value="设备名称"),@ApiImplicitParam(name="deviceId",value="设备国标ID",required=true)})@ApiResponses(@ApiResponse(code = 200, message = "获取到的采集设备信息的列表"))@RequestMapping(value = "", method = RequestMethod.GET)public APEList getQueryApes(HttpServletRequest request,@RequestParam String name,@RequestParam String deviceId){return new APEList();}

@ApiParam

使用场景

​ 用在请求的方法参数上

属性

属性名称 数据类型 默认值 说明
name String “” 参数名
value String “” 参数的汉字说明、解释
required 参数是否必须传

代码示例

    @ApiOperation(value = "批量获取采集设备", notes = "根据上传的信息获取采集设备")@ApiResponses(@ApiResponse(code = 200, message = "获取到的采集设备信息的列表"))@RequestMapping(value = "", method = RequestMethod.GET)public APEList getQueryApes(HttpServletRequest request,@RequestParam @ApiParam(value = "设备名称", required = true)String name,@RequestParam @ApiParam(value = "设备国标ID", required = true)String deviceId) throws Exception {return new APEList();}

UI效果展示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-zmTZmKN2-1587184802823)(C:\Users\jiongming.liao\AppData\Roaming\Typora\typora-user-images\image-20200417204624911.png)]

SpringBoot 集成 Swagger2相关推荐

  1. springboot集成swagger2测试接口

    springboot集成swagger2测试接口 1.需要的依赖 2.开始编写一个swagger2 3.演示效果图片 1.需要的依赖 <dependency><groupId> ...

  2. springboot集成swagger2多模块中文配置详细步骤，解决集成mybatis或mybatis-plus无法正常使用问题

    springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题 参考文章: (1)springboot集成swagger2多模块中文配 ...

  3. 13.9 SpringBoot集成Swagger2中遇到的问题

    13.9 SpringBoot集成Swagger2中遇到的问题 我们在使用SpringBoot集成Swagger2中,访问:http://127.0.0.1:8188/swagger-ui.html ...

  4. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

  5. springboot集成swagger2，构建优雅的Restful API

    springboot集成swagger2,构建优雅的Restful API 转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/ ...

  6. SpringBoot集成Swagger2自动生成友好的RestApi测试页面及文档

    springBoot集成swagger2 水煮鱼又失败了 https://www.jianshu.com/p/002ce2f26103 1 背景 springBoot作为微服务首选框架,为其他服务提供 ...

  7. 【快速上手系列】使用Springboot集成Swagger2的简单使用测试

    [快速上手系列]使用Springboot集成Swagger2的简单使用测试 简介 Swagger2是为了解决企业中接口(api)中定义统一标准规范的文档生成工具. 尤其是前后端分离时对一些业务接口也不 ...

  8. SpringBoot集成Swagger2

    SpringBoot集成Swagger2 刚开始用2.0.2.RELEASE版本的SpringBoot去继承2.7.0版本的springfox-swagger2一直出现请求下面这种情况,就是在启动Sp ...

  9. SpringBoot集成Swagger2与Swagger3的区别

    SpringBoot集成Swagger2与Swagger3的区别 前言 一.pom文件中引入Swagger依赖 Swagger2 Swagger3 二.Swagger配置 Swagger2 Swagg ...

  10. springboot集成swagger2页面出现swagger-resources404

    springboot集成swagger2页面出现swagger-resources404 问题描述 访问/doc.html出现页面,但是没有接口文档,查看页面元素发现问题: /swagger-reso ...

最新文章

  1. 并发编程之多进程篇之四
  2. Java实践（四）——数组
  3. Java多线程-线程通信
  4. 舞台现场直播技术实践
  5. mvc:default-servlet-handler/作用
  6. 人的幸福感取决于什么
  7. python print(f)执行将报错_Linux中为什么执行自己的程序要在前面加./
  8. msf监听php反弹shell,使用msf进行反弹shell+内网渗透
  9. MyBatis动态插入的实现
  10. java压测请求线程数_jmeter压力测试 设置一秒发送一次请求，一秒两次请求
  11. JAVA生成企业组织机构代码、营业执照代码、税务登记号码、统一社会信用代码并校验
  12. 从autotool迁移到cmake
  13. 云呐|国有资产管理信息系统,资产管理信息系统功能描述
  14. 微信发送文件卡死或黑屏
  15. 看完微信公众号最新的广告分成方案，只想给32个赞
  16. 微信公众号教程（10）公众账号自定义回复功能
  17. WSL登录失败：未授权用户再次计算机上的请求登录类型
  18. android语音控制歌曲播放,发条 - 支持音乐聚合搜索，歌单导入，语音控制的 APP - Android 应用 - 【最美应用】...
  19. 学习笔记| AS入门（三） 布局篇
  20. C++版 PPyolo+部署记录

热门文章

  1. 插件9：去掉重音符号
  2. [Windows10]BitLocker解锁经验分享
  3. SpringBoot创建项目依赖爆红
  4. stm32使用红黑树
  5. Revit二次开发入门教程一（工具篇）
  6. Linux命令初步-羽飞作品
  7. k8s使用volume将ConfigMap作为文件或目录直接挂载_NET Core + Kubernetes：Volume
  8. springboot+websocket+sockjs进行消息推送【基于STOMP协议】
  9. 数据挖掘/机器学习/算法岗2017校招面试总结
  10. [转载]BBC镜头下的2012年世锦赛