SpringCloudGatway整合kenfe4j文档

开发环境

• IDEA
• JDK17
• MAVEN 3.6
• SpringCloud 2022.0.1
• SpringBoot 3.0.2

实现方案

1. 子服务集成kenfe4j
2. Gateway整合knfe4j

这里尤其需要注意的是，子服务要统一使用的api

服务配置

子服务配置

pom.xml

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
                <version>2.1.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>

配置类

import cn.hutool.core.util.StrUtil;
import com.crmzf.common.config.handler.OpenApiHandler;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Paths;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.*;
import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
import org.springdoc.core.providers.JavadocProvider;
import org.springframework.boot.autoconfigure.AutoConfigureBefore;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.boot.autoconfigure.web.ServerProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.Optional;

/**
 * SpringDocConfig 文档配置
 *
 * @author dawang
 */
@RequiredArgsConstructor
@Configuration
public class SpringDocConfig {


    private static final String SECURITY_SCHEME_NAME = "Authorization";

    @Bean
    public OpenAPI openApi() {
        return new OpenAPI().info(new Info().title("paper-api").description("xxxx-api").version("v1.0.0"))
                .externalDocs(new ExternalDocumentation().description("xxxx服务").url("http://localhost:10003"))
                .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
                .components(new Components().addSecuritySchemes(SECURITY_SCHEME_NAME, new SecurityScheme().name(SECURITY_SCHEME_NAME).type(SecurityScheme.Type.HTTP)
                        .scheme("Bearer").bearerFormat("JWT")));
    }


}

yaml配置

server:
  port: 10003

spring:
  application:
    name: system-user-api
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        username: nacos
        password: nacos



# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    tags-sorter: alpha
    operations-sorter: alpha
    # 持久化认证数据，如果设置为 true，它会保留授权数据并且不会在浏览器关闭/刷新时丢失
    persistAuthorization: true
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
logging:
  level:
    root: debug

确保子服务可以正常访问

http://localhost:10003/swagger-ui/index.html

http://localhost:10003/doc.htm

网关配置

pom.xml

  <dependencies>
        <!-- gateway网关 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
        <!-- nacos服务注册与发现 -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <!--客户端负载均衡loadbalancer-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-loadbalancer</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

        <!--网关聚合接口文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
             <version>4.1.0</version>
        </dependency>

    </dependencies>

yaml配置

server:
  port: 10002

spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        username: nacos
        password: nacos
   
    gateway:
      discovery:
        locator:
          enabled: true #enabled：默认为false，设置为true表明spring cloud gateway开启服务发现和路由的功能，网关自动根据注册中心的服务名为每个服务创建一个router，将以服务名开头的请求路径转发到对应的服务
          lower-case-service-id: true  # lowerCaseServiceId：启动 locator.enabled=true 自动路由时，路由的路径默认会使用大写ID，若想要使用小写ID，可将lowerCaseServiceId设置为true

      #全局跨域配置
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods:
              - GET
              - POST
              - DELETE
              - PUT
              - OPTION


knife4j:
  gateway:
    enabled: true #生产环境关闭接口文档
    # 指定服务发现的模式聚合微服务文档，并且是默认`default`分组
    strategy: discover
    discover:
      enabled: true
      # 指定版本号(Swagger2|OpenAPI3)
      version : openapi3
      # 需要排除的微服务(eg:网关服务)
      excluded-services:
        - api-gateway

网关最终效果图

总结

由于JDK和springboot版本的升级和架构转为微服务，在在线接口文档这个方面走了不少弯路，其实就是配置的问题，没有什么难度，就是查资料浪费的时间比较多，大家也要多分享最新资料，共同进步。

Knife4j官网文档地址: