1. 技术文章
  2. SpringBoot整合knife4j

SpringBoot整合knife4j

由 淺唱寂寞╮ 提交于 2020-05-04 00:08:54

官网说明及用法：

简介

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效果图

接口说明

接口调试

个性化设置

接口离线文档

SwaggerModels

个性化设置

个性化设置功能是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>

 

 

 

 

 

 

 

 

 

 

 

 

 

标签
swagger-bootstrap-ui
swagger
Markdown
易学教程内所有资源均来自网络或用户发布的内容，如有违反法律规定的内容欢迎反馈！
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!