Knife4j&Swagger：无注册中心条件下的微服务文档聚合

欢迎并感谢浏览卢小龙的本篇文章

你好！亲爱的读者，本篇文章将主要记录本人在无Eureka、Nacos等注册中心的条件下，完成Swagger&Knife4j的多微服务文档聚合，方便自己的学习历程记录以及复习参考，若有言错之处，请各位给予指点.

问题描述

笔者公司目前正在对传统注册中心下线，启用公司内部使用的网关系统，于是乎就出现了无注册中心的微服务如何聚合swagger文档的问题，文档为什么要聚合呢？我们用过swagger的开发者都知道，每个系统都对应一个接口文档页面管理起来着实麻烦。于是就诞生了聚合文档平台

问题解决

1.添加依赖
首先要有一个文档聚合的服务，可以起名为doc系统。在这个系统中添加如下依赖（版本有优化，见文章末尾说明）

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>

	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
	
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.9</version>

	<!-- swagger聚合 -->
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
	<version>2.0.9</version>

2.添加配置

#knife4j聚合,启用cloud模式
knife4j.enableAggregation = true
knife4j.cloud.enable = true
#scrm-core-p1环境
knife4j.cloud.routes[0].name = xxxx
knife4j.cloud.routes[0].uri = 10.164.204.xxx:xxxx
knife4j.cloud.routes[0].location = /v2/api-docs?group=xxx
knife4j.cloud.routes[0].order = 0

3.添加配置类

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/************************************************
 * @Description: Knife4j文档聚合配置类
 * @Author: xiaolong
 * @Date: 2022/11/11
 *************************************************/
@Configuration
@EnableKnife4j
@EnableSwagger2
public class Knife4jDocConfiguration {
    /**
     * 服务名称
     */
    @Value("${spring.application.name:应用}")
    private String appName;

    /**
     * 引入Knife4j提供的扩展类 OpenApiExtensionResolver辅助类需要配置knife4j.enable=true才能自动@Autowired
     */
    @Autowired(required = false)
    private OpenApiExtensionResolver openApiExtensionResolver;

    /**
     * 1、限制哪些类可以生成api文档 2、限制哪些url可以生成api文档
     */
    @Bean
    @ConditionalOnMissingBean
    public Docket apiDocket() {
        // 默认组名, 文档更具组名查询,不同组名不能聚合
        String groupName = "default";
        return new Docket(DocumentationType.SWAGGER_2)
                // 文档信息
                .apiInfo(getApiInfo())
                // 组名
                .groupName(groupName)
                .select()
                // 指定Controller扫描包路径(如下面第一个apis方法)     因Controller类上要添加Api注解, 所以可通过指定类上注解
                // .apis(RequestHandlerSelectors.basePackage("com.haier.xxx.manager.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                // 赋予插件体系
                .extensions(getExtensions(groupName));
    }


    /**
     * 创建api文档信息
     */
    private ApiInfo getApiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title(appName + "服务接口文档")
                // 描述
                .description("接口的相关文档")
                // 作者信息
                .contact(new Contact("运营平台", "https://ones.haiercash.com/wiki/#/team/XMXRSk94/space/3FU7siVS/page/5jUqyUtb", "haiercash.com"))
                // 版本
                .version("1.0")
                .build();
    }

    /**
     * 根据组名添加插件
     */
    private List<VendorExtension> getExtensions(String groupName) {
        return null != openApiExtensionResolver ? openApiExtensionResolver.buildExtensions(groupName) : new ArrayList<>();
    }
}

打开doc系统的knife4j首页后，就可以发现，已经完成文档聚合。

补充点：
2022年12月5日发现问题：#I64P8J:Knife4jAggregation聚合文档，Cloud模式，服务重启后分组不见了

给官方提了Issue之后，予以修复，以后使用4.0.0快照版本及以上版本

	<!-- swagger聚合 -->
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
	<version>4.0.0-SNAPSHOT</version>