Spring Cloud Gateway 整合knife4j 聚合微服务swagger3

1. 搭建单服务swagger

1.1 引入依赖

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        dependency>

1.2 application启用swagger

@EnableOpenApi

1.3 新增swagger配置类

package com.admin.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author zr
 * @date 2023/4/10 14:23
 */
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("更多请咨询服务开发者Ray。")
                .contact(new Contact("zr", "http://www.baidu.com", "[email protected]"))
                .version("1.0")
                .build();
    }
}

1.4 controller添加接口信息

1.5 启动服务访问测试

因为我是微服务所以端口号后面加上服务名admin-service

http://localhost:8090/admin-service/swagger-ui/index.html#/

效果如下

2. 使用knife4j通过Gateway聚合swagger

2.1 非网关服务整合knife4j

在原来单节点模块下引入knife4j-micro依赖

• knife4j-micro-spring-boot-starter是不带swagger依赖的

• knife4j-spring-boot-starter是带swagger依赖的

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-micro-spring-boot-starterartifactId>
    <version>3.0.3version>
dependency>

为了展示knife4j的聚合效果所以我们至少要有两个模块,新增一个模块按照搭建单服务swagger再次整合一个服务(记得新服务依赖也需要引入knife4j-micro依赖)

2.2 Gateway网关整合knife4j

最后我们搭建网关服务，作为微服务API文档的的统一入口，聚合所有微服务的API文档。

2.2.1 引入依赖

        
        <dependency>
            <groupId>com.github.xiaoymingroupId>
            <artifactId>knife4j-spring-boot-starterartifactId>
            <version>3.0.3version>
        dependency>

2.2.2 application.yml

在application.yml这添加相关配置，配置一下Nacos注册中心，用户服务和订单服务的路由即可；

server:
  port: 8088
spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      routes:
        - id: admin_route  #路由唯一标识
          uri: lb://admin-service  #需要转发的地址 http://localhost:8020 lb:使用nacos本地负载均衡策略
        - id: non_route  #路由唯一标识
          uri: lb://non-service  #需要转发的地址 http://localhost:8020 lb:使用nacos本地负载均衡策略
        - id: log_route  #路由唯一标识
          uri: lb://logger-service  #需要转发的地址 http://localhost:8020 lb:使用nacos本地负载均衡策略
      globalcors: #跨域配置
        cors-configurations:
          '[/**]': #允许跨域访问的资源
            allowedOrigins: "*"  #跨域允许来源
            allowedMethods: # 允许的请求
              - GET
              - POST
              - OPTIONS
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos

2.2.3 Swagger资源配置SwaggerResourceConfig

在网关上添加Swagger资源配置，用于聚合其他微服务中Swagger的api-docs访问路径；

package com.gateway.config;

import lombok.AllArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

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

/**
 * @author zr
 * @date 2023/4/10 15:02
 */
@Slf4j
@Component
@Primary
@AllArgsConstructor
public class SwaggerResourceConfig implements SwaggerResourcesProvider {

    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        //获取所有路由的ID
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        //过滤出配置文件中定义的路由->过滤出Path Route Predicate->根据路径拼接成api-docs路径->生成SwaggerResource
        gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
            route.getPredicates().stream()
                    .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                    .forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),
                            predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                                    .replace("**", "v2/api-docs"))));
        });

        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        log.info("name:{},location:{}", name, location);
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}

什么是Swagger的api-docs访问路径？

该路径会返回JSON格式数据，Swagger渲染API文档页面的所有数据就是来源于此，比如我们的用户服务会返回如下信息，访问地址：http://localhost:8088/api/logger-service/v2/api-docs

2.2.4 自定义Swagger各个配置的节点SwaggerHandler

自定义Swagger各个配置的节点，简单来说就是自定义Swagger内部的各个获取数据的接口；

package com.gateway.handler;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;

import java.util.Optional;

/**
 * @author zr
 * @date 2023/4/10 15:04
 */
@RestController
public class SwaggerHandler {

    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;

    @Autowired(required = false)
    private UiConfiguration uiConfiguration;

    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
        this.swaggerResources = swaggerResources;
    }

    /**
     * Swagger安全配置，支持oauth和apiKey设置
     */
    @GetMapping("/swagger-resources/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    /**
     * Swagger UI配置
     */
    @GetMapping("/swagger-resources/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    /**
     * Swagger资源配置，微服务中这各个服务的api-docs信息
     */
    @GetMapping("/swagger-resources")
    public Mono<ResponseEntity> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

2.2.5 功能演示

展示knife4j的聚合swagger效果,仅需要访问网关的API文档页面即可，可自行切换到相关服务的API文档。

• 在此之前先启动我们的Nacos注册中心，然后依次启动网关服务和其他两个集成swagger的服务；

  

• 从网关访问API文档，访问地址：http://localhost:8088/doc.html

  

  此处可以看出knife4j的服务选择是根据网关配置的路由来的我的non-router没有整合swagger与knife4j出现在下拉框

  但是点击会报错:

  

  如果需要聚合该服务只需要按照章节1与章节2.1整合即可

3. sa-token 全局过滤器 knife4j 接口文档访问失败

此处我使用的是satoken,如果读者使用的spring security或者其他权限认证可以自行百度放行方式,只要将对应路径放行即可

如果在2.2.5访问http://localhost:8088/doc.html被拦截

只需要将以下资源路径放行即可

重启网关访问http://localhost:8088/doc.html即可