官网说明及用法:

简介

swagger-bootstrap-ui是springfox-swagger的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验

核心功能

该UI增强包主要包括两大核心功能:文档说明 和 在线调试

  • 文档说明:根据Swagger的规范说明,详细列出接口文档的说明,包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息,使用swagger-bootstrap-ui能根据该文档说明,对该接口的使用情况一目了然。

  • 在线调试:提供在线接口联调的强大功能,自动解析当前接口参数,同时包含表单验证,调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息,帮助开发者在线调试,而不必通过其他测试工具测试接口是否正确,简介、强大。

UI增强

同时,swagger-bootstrap-ui在满足以上功能的同时,还提供了文档的增强功能,这些功能是官方swagger-ui所没有的,每一个增强的功能都是贴合实际,考虑到开发者的实际开发需要,是比不可少的功能,主要包括:

  • 个性化配置:通过个性化ui配置项,可自定义UI的相关显示信息

  • 离线文档:根据标准规范,生成的在线markdown离线文档,开发者可以进行拷贝生成markdown接口文档,通过其他第三方markdown转换工具转换成html或pdf,这样也可以放弃swagger2markdown组件

  • 接口排序:自1.8.5后,ui支持了接口排序功能,例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序,step化接口操作,方便其他开发者进行接口对接

UI特点

  • 以markdown形式展示文档,将文档的请求地址、类型、请求参数、示例、响应参数分层次依次展示,接口文档一目了然,方便开发者对接
  • 在线调试栏除了自动解析参数外,针对必填项着颜色区分,同时支持tab键快速输入上下切换.调试时可自定义Content-Type请求头类型
  • 个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能
  • 接口排序,支持分组及接口的排序功能
  • 支持markdown文档离线文档导出,也可在线查看离线文档
  • 调试信息全局缓存,页面刷新后依然存在,方便开发者调试
  • 以更人性化的treetable组件展示Swagger Models功能
  • 响应内容可全屏查看,针对响应内容很多的情况下,全屏查看,方便调试、复制
  • 文档以多tab方式可显示多个接口文档
  • 请求参数栏请求类型、是否必填着颜色区分
  • 主页中粗略统计接口不同类型数量
  • 支持接口在线搜索功能
  • 左右菜单和内容页可自由拖动宽度
  • 支持自定义全局参数功能,主页包括header及query两种类型
  • i18n国际化支持,目前支持:中文简体、中文繁体、英文
  • JSR-303 annotations 注解的支持

UI效果图

个性化设置

个性化设置功能是SwaggerBootstrapUi针对本身Ui特点提供的个性化设置功能,主要包括:

  • 开启请求参数缓存
  • 菜单Api地址显示
  • 分组tag显示description说明属性
  • 开启RequestMapping接口类型重复地址过滤
  • 开启SwaggerBootstrapUi增强功能.

功能目录:文档管理 -> 个性化设置

开启请求参数缓存

此功能在在线调试时可见效果,当针对每个接口点击发送调试查看后,后面打开该接口再调试时,默认为保留上一次发送的接口参数信息

如果不想开启此缓存,不勾选此项即可.默认为true,即开启状态

菜单Api地址显示

菜单Api地址显示是在左侧菜单不显示api地址信息,默认为false,即不显示,默认效果如下图 

如果需要左侧菜单栏显示接口地址,则勾选此项接口,显示效果图如下:

分组tag显示description说明属性

tag是否显示代码中的description属性,默认为false,及不显示,如果勾选显示description属性,效果图如下:

开启RequestMapping接口类型重复地址过滤

针对后端RequestMapping注解类型的接口,如果开发者没有指定接口类型,默认使用Swagger会生成七个不同类型的接口地址,效果图如下:

再某些情况下,开发者可能需要过滤,简化重复的接口文档,此时,开发者通过勾选此选项,并在后面选择显示接口类型的选项,SwaggerBootstrapUi会根据此选项自动过滤

例如勾选,然后默认显示Post类型,则效果如下:

此项默认为false,即不开启此项(不过滤).

开启SwaggerBootstrapUi增强功能

全局搜索

SwaggerBootstrapUi提供了全局搜索功能,当开发者不清楚某一接口时,可使用搜索功能快速定位到接口文档

搜索关键字主要包括:URL地址、接口说明、方法类型、接口描述

全局参数

SwaggerBootstrapUi提供基于UI临时设置全局参数功能,例如后台全局token参数等.

目前全局参数功能主要提供两种参数类型:query(表单)、header(请求头)

该功能是在还没有支持全局参数时临时配置的功能,如果后端Swagger有配置全局参数,该功能可以无视

功能目录:文档管理 -> 全局参数设置

个性化设置

个性化设置功能是SwaggerBootstrapUi针对本身Ui特点提供的个性化设置功能,主要包括:

  • 开启请求参数缓存
  • 菜单Api地址显示
  • 分组tag显示description说明属性
  • 开启RequestMapping接口类型重复地址过滤
  • 开启SwaggerBootstrapUi增强功能.

功能目录:文档管理 -> 个性化设置

开启请求参数缓存

此功能在在线调试时可见效果,当针对每个接口点击发送调试查看后,后面打开该接口再调试时,默认为保留上一次发送的接口参数信息

如果不想开启此缓存,不勾选此项即可.默认为true,即开启状态

菜单Api地址显示

菜单Api地址显示是在左侧菜单不显示api地址信息,默认为false,即不显示,默认效果如下图 

如果需要左侧菜单栏显示接口地址,则勾选此项接口,显示效果图如下:

分组tag显示description说明属性

tag是否显示代码中的description属性,默认为false,及不显示,如果勾选显示description属性,效果图如下:

开启RequestMapping接口类型重复地址过滤

针对后端RequestMapping注解类型的接口,如果开发者没有指定接口类型,默认使用Swagger会生成七个不同类型的接口地址,效果图如下:

再某些情况下,开发者可能需要过滤,简化重复的接口文档,此时,开发者通过勾选此选项,并在后面选择显示接口类型的选项,SwaggerBootstrapUi会根据此选项自动过滤

例如勾选,然后默认显示Post类型,则效果如下:

此项默认为false,即不开启此项(不过滤).

开启SwaggerBootstrapUi增强功能

代码展示:

配置类

/**
* @author WGR
* @create 2019/12/1 -- 20:00
*/
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.topcheer.knife4j.web"))
.paths(PathSelectors.any())
.build(); } private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-bootstrap-ui RESTful APIs")
.description("swagger-bootstrap-ui")
.termsOfServiceUrl("http://localhost:8999/")
.contact("developer@mail.com")
.version("1.0")
.build();
} }

Model层

/**
* @author WGR
* @create 2019/12/1 -- 20:02
*/
@ApiModel("通用接口返回对象")
public class Results<T> { @ApiModelProperty(required = true,notes = "结果码",example = "200")
private int state;
@ApiModelProperty(required = true,notes = "时间戳",example = "1567425139000")
private long time;
@ApiModelProperty(required = true,notes = "返回信息",example = "SUCCESS")
private String message;
@ApiModelProperty(required = true,notes = "返回数据",example = "{\"name\":\"blues\"}")
private T content; public Results(int code, String msg, T obj){
setState(code);
setMessage(msg);
setContent(obj);
setTime(System.currentTimeMillis());
} public int getState() {
return state;
} public void setState(int state) {
this.state = state;
} public long getTime() {
return time;
} public void setTime(long time) {
this.time = time;
} public String getMessage() {
return message;
} public void setMessage(String message) {
this.message = message;
} public T getContent() {
return content;
} public void setContent(T content) {
this.content = content;
}
} /**
* @author WGR
* @create 2019/12/1 -- 20:02
*/
@ApiModel("用户对象")
public class UserVO { @ApiModelProperty(required = true,notes = "用户名",example = "blues")
private String name; @ApiModelProperty(required = true,notes = "用户返回消息",example = "hello world")
private String words; public UserVO(String name, String words) {
this.name = name;
this.words = words;
} public String getName() {
return name;
} public void setName(String name) {
this.name = name;
} public String getWords() {
return words;
} public void setWords(String words) {
this.words = words;
}
}

Web层

/**
* @author WGR
* @create 2019/12/1 -- 20:01
*/
@Api(tags = "HELLO CONTROLLER 测试功能接口")
@RestController
public class HelloController { @ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户名称",required = true,dataType = "String",paramType = "path",example = "blues")
})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "接口返回成功状态"),
@ApiResponse(code = 500, message = "接口返回未知错误,请联系开发人员调试")
})
@ApiOperation(value = "Hello 测试接口", notes = "访问此接口,返回hello语句,测试接口")
@GetMapping("hello/{name}")
public Results<UserVO> hello(@PathVariable String name){
UserVO userVO = new UserVO(name,"hello " + name);
Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
return results;
} }

pom.xml

<dependencies>
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>1.9.6</version>
</dependency> <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency> <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>

SpringBoot整合knife4j的更多相关文章

  1. SpringBoot整合knife4j框架(可生成离线接口文档),并设置接口请求头token默认值

    功能和swagger类似 官网地址:https://doc.xiaominfo.com/knife4j/ 这个框架可以设置返回字段的描述 引入依赖 <dependency> <gro ...

  2. Springboot中整合knife4j接口文档

    在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发. 什么是knife4j 简单说knife4j就swagge ...

  3. spring-boot整合mybatis(1)

    sprig-boot是一个微服务架构,加快了spring工程快速开发,以及简便了配置.接下来开始spring-boot与mybatis的整合. 1.创建一个maven工程命名为spring-boot- ...

  4. SpringBoot整合Mybatis之项目结构、数据源

    已经有好些日子没有总结了,不是变懒了,而是我一直在奋力学习springboot的路上,现在也算是完成了第一阶段的学习,今天给各位总结总结. 之前在网上找过不少关于springboot的教程,都是一些比 ...

  5. springboot整合mq接收消息队列

    继上篇springboot整合mq发送消息队列 本篇主要在上篇基础上进行activiemq消息队列的接收springboot整合mq发送消息队列 第一步:新建marven项目,配置pom文件 < ...

  6. springboot整合mybaits注解开发

    springboot整合mybaits注解开发时,返回json或者map对象时,如果一个字段的value为空,需要更改springboot的配置文件 mybatis: configuration: c ...

  7. SpringBoot整合Redis、ApachSolr和SpringSession

    SpringBoot整合Redis.ApachSolr和SpringSession 一.简介 SpringBoot自从问世以来,以其方便的配置受到了广大开发者的青睐.它提供了各种starter简化很多 ...

  8. SpringBoot整合ElasticSearch实现多版本的兼容

    前言 在上一篇学习SpringBoot中,整合了Mybatis.Druid和PageHelper并实现了多数据源的操作.本篇主要是介绍和使用目前最火的搜索引擎ElastiSearch,并和Spring ...

  9. SpringBoot整合Kafka和Storm

    前言 本篇文章主要介绍的是SpringBoot整合kafka和storm以及在这过程遇到的一些问题和解决方案. kafka和storm的相关知识 如果你对kafka和storm熟悉的话,这一段可以直接 ...

随机推荐

  1. Java中关于Date等日期类的简单使用

    Date Date类不常用,很多方法被废弃了,常用它的两个构造方法来new一个Date对象. Date d1 = new Date(); //不传任何参数,代表当前时间点 System.out.pri ...

  2. Java程序的运行过程,以及Java为什么能够跨平台

    Java程序运行机制  Java的运行主要分两步:先编译再解释执行 (1)先通过“编译器”将Java源程序(.java)编译成Java字节码文件(.class) (2)通过不同的虚拟机(JVM)将字节 ...

  3. JDK8中接口的新特性

    在JDK8环境中,接口中的方法不再是只能有抽象方法,还可以有静态方法和default方法.实现类只需要实现它的抽象方法即可,JDK8中的接口有愈发向抽象类靠拢的感觉. 关于静态方法和默认方法作如下简述 ...

  4. CentOSLinux安装Docker容器

    Docker 使用 环境说明 CentOS 7.3(不准确地说:要求必须是 CentOS 7 64位) 不建议在 Windows 上使用 Docker 基本概念 官网:https://www.dock ...

  5. [转帖]Docker从入门到动手实践

    Docker从入门到动手实践 https://www.cnblogs.com/nsky/p/10853194.html dockerfile的图很好呢. 但是自己没有做实验 , 其实知识都挺好. do ...

  6. 【监控实践】【4.1】利用trace实现阻塞跟踪和慢查询跟踪

    原文:https://blog.csdn.net/kk185800961/article/details/49252037 分享个SQLServer profiler 的一个技巧吧.很早用过,忘记总结 ...

  7. vue router应用及总结

    编写一个小的demo,对router基础的应用学习和理解. 效果图示: 说明: 点击About在右边显示相关信息. 说明: 点击Home,在下边显示相关信息,且Home下有两个路由链接,分别对应各自的 ...

  8. es6 js数组常用方法

    一:会改变自身的方法 1.array.push(element1, ...elementN) 添加一个或多个元素到数组的末尾,并返回数组新的长度 2.array.unshift(element1, . ...

  9. lambda map() filter() zip()练习

    练习: 用map来处理字符串列表,把列表中所有人都变成sb,比方alex_sb l=[{'name':'alex'},{'name':'y'}] l=[{'name':'alex'},{'name': ...

  10. 通过编写串口助手工具学习MFC过程--(十一)弹出模态型对话框

    通过编写串口助手工具学习MFC过程 因为以前也做过几次MFC的编程,每次都是项目完成时,MFC基本操作清楚了,但是过好长时间不再接触MFC的项目,再次做MFC的项目时,又要从头开始熟悉.这次通过做一个 ...