【Knife4j】小试牛刀，基于eureka的集成

小尘哥
380 阅读4分钟

knife4j是什么?可以关注一下官网，简单说就是对基于swagger的增强版本。【官网】 本文基于以下基础进行集成：

  1. springboot 2.7.0（2.6.7+也可，推荐使用GA版本）
  2. knife4j3.0.3
  3. knife4j-aggregation 2.0.9
  4. spring cloud 2021.0.1
  5. 本文基于eureka集成（后续会介绍基于gateway的集成方式）

一、工程结构

3.png

使用到的工程说明：

  • eboot-center:eureka注册中心（服务端）
  • eboot-knife4j:文档服务
  • eboot-common:包含了一些基础的认证、全局异常等处理，本文暂不需要
  • eboot-gateway:spring-cloud-gateway，大多是情况下微服务均走网关，下一步会实现基于gateway的knife集成
  • eboot-modulars:即各个业务子系统，这里分了三个：认证管理、文件管理、系统管理
  • eboo-ui：前端项目，本文不需要

二、eboot-center服务端

普通的eureka服务端配置

主要配置如下：

         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>
         </dependency>
         <dependency>
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
         </dependency>

 server:
   port: 8761
 eureka:
   instance:
     hostname: localhost
     appname: eboot-provider
     leaseRenewalIntervalInSeconds: 1
     lease-expiration-duration-in-seconds: 2
     prefer-ip-address: true
   client:
     registerWithEureka: false
     fetchRegistry: false
     serviceUrl:
       defaultZone: http://localhost:8761/eureka/
 spring:
   boot:
     admin:
       client:
         url: http://localhost:8888
   application:
     name: boot-provider

三、eboot-knife4j服务配置

文档服务的主要配置均在此，其实它只是一个web工程，详细配置参数见【eureka参数配置】

主要配置如下：

        <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>
         </dependency>
         <dependency>
             <groupId>com.github.xiaoymin</groupId>
             <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
         </dependency>

请注意以下的serviceName和location: *1. serviceName：eureka是根据这个进行接口统计请求的，因此这个一定一定要正确，和对应服务中的对应起来。 *2. location：业务系统起来之后可以访问下这个地址试试是否可以正常返回json数据，注意group，未配置的话是default，如果配置了使用业务系统配置的即可（例如：boot-auth的分组我使用了auth）

 server:
   port: 9999
 knife4j:
   enableAggregation: true
   setting:
     footerCustomContent: Copyright 2022-2023 【小尘哥】
   eureka:
     enable: true
     serviceUrl: http://127.0.0.1:8761/eureka/
     routeAuth:
       enable: true
       username: admin
       password: 123456
     routes:
       - name: 认证体系
         serviceName: boot-auth
         location: http://localhost:9091/auth/v2/api-docs?group=auth
         servicePath: /auth
       - name: 文件服务
         serviceName: boot-file
         location: http://localhost:9092/file/v2/api-docs?group=default
         servicePath: /file
       - name: 系统服务
         serviceName: boot-system
         location: http://localhost:9093/system/v2/api-docs?group=default
         servicePath: /system
 ​

放行静态资源和解决跨域问题

注意： 跨域问题在每个服务中均需解决，否则接口请求报错

     @Override
     public void addResourceHandlers(ResourceHandlerRegistry registry) {
         //配置拦截器访问静态资源
         registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
         registry.addResourceHandler("/favicon.ico").addResourceLocations("classpath:/META-INF/resources/");
         registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
     }
 ​
     private CorsConfiguration buildConfig() {
         CorsConfiguration corsConfiguration = new CorsConfiguration();
         corsConfiguration.addAllowedOrigin("*");
         corsConfiguration.addAllowedHeader("*");
         corsConfiguration.addAllowedMethod("*");
         return corsConfiguration;
     }
 ​
     @Bean
     public CorsFilter corsFilter() {
         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
         source.registerCorsConfiguration("/**", buildConfig());
         return new CorsFilter(source);
     }

四、业务系统系统

基本和普通的集成swagger一样，以下以eboot-auth为例，只列出关键配置

  1. 启用eureka客户端
  2. 集成knife
  3. 加入guava,否则swagger可能会有各种奇葩问题
   <dependency>
       <groupId>org.springframework.cloud</groupId>
       <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
     </dependency>
     <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-micro-spring-boot-starter</artifactId>
     </dependency>
     <dependency>
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
  • knife4j.enable:启用knife增强功能，否则就是普通的swagger
  • spring.mvc.pathmatch.matching-strategy，springboot 2.6.0开始MVC 处理映射匹配的默认策略已从AntPathMatcher更改为PathPatternParser，但是knife依然是AntPathMatcher模式，因此需手动修改回去，否则会出现“Failed to start bean ‘ documentationPluginsBootstrapper ‘”
  • 其他的eureka正常配置即可
 eureka:
   client:
     serviceUrl:
       defaultZone: http://127.0.0.1:8761/eureka/
   instance:
     appname: boot-auth
     leaseRenewalIntervalInSeconds: 1
     lease-expiration-duration-in-seconds: 2
     prefer-ip-address: true
     instance-id: 127.0.0.1:9091
 knife4j:
   enable: true
 spring:
   mvc:
     pathmatch:
       matching-strategy: ant_path_matcher

swagger配置如下：

     @Bean
     @Order(value = 1)
     public Docket groupRestApi() {
         Contact contact = new Contact("小尘哥","http://localhost:9091/auth/","grq100296@163.com");
         Docket docket=new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(new ApiInfoBuilder()
                         .title("统一认证服务 RESTful APIs")
                         .description("统一认证服务相关接口")
                         .termsOfServiceUrl("http://localhost:9091/auth/")
                         .contact(contact)
                         .version("1.0")
                         .build())
                 //分组名称
                 .groupName("auth")
                 .select()
                 //这里指定Controller扫描包路径
                 .apis(RequestHandlerSelectors.basePackage("com.mos.eboot.auth.controller"))
                 .paths(PathSelectors.any())
                 .build();
         return docket;
     }

接口示例，请注意@ApiSupport即为knife增强注解，可以为当前类或者接口增加作者、序号等。包括@DynamicParameter、@DynamicResponseParameters、ApiOperationSupport、@Ignore等

package com.mos.eboot.auth.controller;


import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import com.mos.eboot.auth.entity.SysUser;
import com.mos.eboot.auth.form.LoginBody;
import com.mos.eboot.auth.service.ISysUserService;
import com.mos.eboot.commom.core.auth.domain.LoginUser;
import com.mos.eboot.commom.core.result.ResultModel;
import com.mos.eboot.commom.core.result.ResultStatus;
import com.mos.eboot.commom.core.util.JwtUtils;
import com.mos.eboot.common.security.auth.AuthUtil;
import com.mos.eboot.common.security.service.TokenService;
import com.mos.eboot.common.security.util.SecurityUtils;
import com.xiaoleilu.hutool.util.ObjectUtil;
import com.xiaoleilu.hutool.util.StrUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;
import java.util.Map;

/**
 * token 控制
 *
 * @author 小尘哥
 */
@Api(tags = "token认证")
@ApiSupport(author = "小尘哥")
@RestController
public class TokenController {
    @Autowired
    private TokenService tokenService;

    @Autowired
    private ISysUserService sysUserService;

    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名",required = true),
            @ApiImplicitParam(name = "password",value = "密码",required = true),
    })
    @ApiOperation(value = "登录")
    @PostMapping("login")
    public ResultModel<Map<String, Object>> login(LoginBody form) {
        // 用户登录
        LambdaQueryWrapper<SysUser> entityWrapper = Wrappers.lambdaQuery();
        entityWrapper.eq(SysUser::getUsername, form.getUsername());
        SysUser sysUser = sysUserService.getOne(entityWrapper);
        LoginUser userInfo = new LoginUser();
        userInfo.setUserid(sysUser.getId());
        userInfo.setUsername(sysUser.getUsername());
        // TODO:  完善LoginUser信息，记录登录日志
        return ResultModel.defaultSuccessObj(tokenService.createToken(userInfo));
    }

}

五、界面展示

4.png

\

avatar
文章
阅读
粉丝