SpringBoot整合knife4j(快速入门超详细版)


😊 @ 作者: Eric
💖 @ 主页: https://blog.csdn.***/weixin_47316183?type=blog
🎉 @ 主题:SpringBoot整合knife4j(快速入门超详细版)
⏱️ @ 创作时间: 2023年08月01日


1、什么是Knife4j

在日常开发中,写接口文档是我们必不可少的,而Knife4j就是一个接口文档工具,可以看作是Swagger的升级版,但是界面比Swagger更好看,功能更丰富

早期,swagger-boostrap-ui是1.x版本,如今swagger-bootsrap-ui到2.x,同时也更改名字Knife4j,适用于单体和微服务项目。

Knife4j官方网站:https://doc.xiaominfo.***/

2、SpringBoor整合Knife4j

2.1、Knife4j配置

1、创建一个SpringBoot项目

2、引入Knife4j相关依赖(这里顺带引入了Lombok依赖)

<dependency>
    <groupId>***.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.8</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

3、创建Knife4J配置类

java">package ***.eric.springbootknife4j.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger2配置信息
 * 这里分了两组显示
 * 第一组是api,当作用户端接口
 * 第二组是admin,当作后台管理接口
 * 也可以根据实际情况来减少或者增加组
 *
 * @author Eric
 * @date 2023-07-30 22:17
 */

@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("Eric-SpringBoot整合Knife4j-API文档")
                .description("本文档描述了SpringBoot如何整合Knife4j")
                .version("1.0")
                .contact(new Contact("Eric", "https://blog.csdn.***/weixin_47316183?type=blog", "ericsyn@foxmail.***"))
                .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("Eric-SpringBoot整合Knife4j-API文档")
                .description("本文档描述了SpringBoot如何整合Knife4j")
                .version("1.0")
                .contact(new Contact("Eric", "https://blog.csdn.***/weixin_47316183?type=blog", "ericsyn@foxmail.***"))
                .build();
    }

    /**
     * 第一组:api
     * @return
     */
    @Bean
    public Docket webApiConfig() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("userId")
                .description("用户token")
                //.defaultValue(JwtHelper.createToken(1L, "admin"))
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());

        Docket webApi = new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户端接口")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .apis(RequestHandlerSelectors.basePackage("***.eric.springbootknife4j"))
                .paths(PathSelectors.regex("/api/.*"))
                .build()
                .globalOperationParameters(pars);
        return webApi;
    }

    /**
     * 第二组:admin
     * @return
     */
    @Bean
    public Docket adminApiConfig() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("adminId")
                .description("用户token")
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());

        Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台接口")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .apis(RequestHandlerSelectors.basePackage("***.eric.springbootknife4j"))
                .paths(PathSelectors.regex("/admin/.*"))
                .build()
                .globalOperationParameters(pars);
        return adminApi;
    }

}

2.2、使用Knife4j

1、创建一个实体类

package ***.eric.springbootknife4j.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Builder;
import lombok.Data;

/**
 * @author Eric
 * @date 2023-07-31 9:55
 */
@ApiModel("用户实体类")
@Data
@Builder
public class SwaggerUser {

    @ApiModelProperty("用户Id")
    private Long id;

    @ApiModelProperty("用户名称")
    private String name;

}

2、对应接口,这里我为了大家看的方便,也是分了两个控制器,也是根据api和admin来分的

admin

package ***.eric.springbootknife4j.admin;

import ***.eric.springbootknife4j.entity.SwaggerUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @author Eric
 * @date 2023-07-31 9:50
 */
@Api(tags = "用户端控制器")
@RestController
@RequestMapping("/admin")
public class AdminController {

    @ApiOperation(value = "获取数据")
    @GetMapping("/test")
    public List<SwaggerUser> test(@ApiParam(name = "id",value = "用户Id") Long id,
                                  @ApiParam(name = "name",value = "用户名称") String name){

        List<SwaggerUser> list = new ArrayList<>();
        list.add(SwaggerUser.builder().id(id).name(name).build());
        return list;
    }
}

api

package ***.eric.springbootknife4j.api;

import ***.eric.springbootknife4j.entity.SwaggerUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @author Eric
 * @date 2023-07-31 9:50
 */
@Api(tags = "用户端控制器")
@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation(value = "获取数据")
    @GetMapping("/test")
    public List<SwaggerUser> test(@ApiParam(name = "id",value = "用户Id") Long id,
                                  @ApiParam(name = "name",value = "用户名称") String name){

        List<SwaggerUser> list = new ArrayList<>();
        list.add(SwaggerUser.builder().id(id).name(name).build());
        return list;
    }
}

2.3、效果

此时运行项目,访问 IP+端口/doc.html
例如:http://127.0.0.1:8080/doc.html


这就是首页

包括也是按照我们的配置文件来分组显示了,这里可根据自己项目的实际情况,按照微服务来分、按照功能目录来分都是可以的

如下就是我们的实体类,发现我们写的注释也都自动生成了

下面就是我们的接口调试界面了

自带路径、接口说明、参数说明,只要我们写了解释,这里都会显示

此时我们也可以点击调试,然后点击发送,就能看到我们的返回信息了,并且如果我们的返回实体类上有注解注释的,这里也是会显示的


总结

怎么样,是不是特别的方便和简单~

转载请说明出处内容投诉
CSS教程_站长资源网 » SpringBoot整合knife4j(快速入门超详细版)

发表评论

欢迎 访客 发表评论

一个令你着迷的主题!

查看演示 官网购买