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

07-14 1829阅读

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

😊 @ 作者: Eric

💖 @ 主页: https://blog.csdn.net/weixin_47316183?type=blog

🎉 @ 主题:SpringBoot整合knife4j(快速入门超详细版)

⏱️ @ 创作时间: 2023年08月01日

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

文章目录

  • 1、什么是Knife4j
  • 2、SpringBoor整合Knife4j
    • 2.1、Knife4j配置
    • 2.2、使用Knife4j
    • 2.3、效果
    • 总结

      1、什么是Knife4j

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

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

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

      2、SpringBoor整合Knife4j

      2.1、Knife4j配置

      1、创建一个SpringBoot项目

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

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

          com.github.xiaoymin
          knife4j-spring-boot-starter
          2.0.8
      
      
          org.projectlombok
          lombok
      
      

      3、创建Knife4J配置类

      package com.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.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
                      .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.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
                      .build();
          }
          /**
           * 第一组:api
           * @return
           */
          @Bean
          public Docket webApiConfig() {
              List 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("com.eric.springbootknife4j"))
                      .paths(PathSelectors.regex("/api/.*"))
                      .build()
                      .globalOperationParameters(pars);
              return webApi;
          }
          /**
           * 第二组:admin
           * @return
           */
          @Bean
          public Docket adminApiConfig() {
              List 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("com.eric.springbootknife4j"))
                      .paths(PathSelectors.regex("/admin/.*"))
                      .build()
                      .globalOperationParameters(pars);
              return adminApi;
          }
      }
      

      2.2、使用Knife4j

      1、创建一个实体类

      package com.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来分的

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

      admin

      package com.eric.springbootknife4j.admin;
      import com.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 test(@ApiParam(name = "id",value = "用户Id") Long id,
                                        @ApiParam(name = "name",value = "用户名称") String name){
              List list = new ArrayList();
              list.add(SwaggerUser.builder().id(id).name(name).build());
              return list;
          }
      }
      

      api

      package com.eric.springbootknife4j.api;
      import com.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 test(@ApiParam(name = "id",value = "用户Id") Long id,
                                        @ApiParam(name = "name",value = "用户名称") String name){
              List 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


      这就是首页

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

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

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

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

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

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

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

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

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

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


      总结

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

VPS购买请点击我

文章版权声明:除非注明,否则均为主机测评原创文章,转载或复制请以超链接形式并注明出处。

目录[+]