SpringCloud Gateway网关统一聚合Swagger接口文档（knife4j），实现通过网关统一文档地址查看所有子服务的接口文档

前言：

在微服务系统中，通常每个服务都会暴露其接口文档，在前端人员或测试人员查看的时候，并不是那么方便，我们需要告诉相关人员每个服务的文档地址，由于swagger/knif4j（knif4j为更易用的swagger封装，点此了解knif4j）支持以rest的方式获取所有微服务的文档数据，再配合Gateway的路由，我们可以轻松的通过其相关API做到聚合文档的效果，做到只提供一个文档地址，便可查看所有微服务下的接口文档

注意：

• 各微服务的knife4j配置及文档访问，观阅此文前默认认为你已经是完成且可访问的，如未完成或遇到问题等，参考knif4j官网按照文档进行操作，或在评论区留言。

• 如果想方便简单的接入，可直接参考、套用我的代码，之前写过一篇文章为Nacos结合Gateway实现动态路由，本文示例代码仍基于其仓库进行编写，仓库地址：springcloud-nacos-example tree:knif4j
  点个关注，来个star，甚是感激 😃

• 以下操作全程在Gateway模块，各微服务模块如果Docket的Group类型（API分组，比如openApi,adminApi,feignApi等）定义统一，则无需改变

一、依赖

Gateway聚合文档服务，需要knif4j的依赖：

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
        </dependency>

本例使用的版本为2.0.9，其他版本的请自行结合并尝试

二、配置

1).自定义配置文件
在resources下新建：swagger-faced.yml（也可放在配置中心，按个人所需）
此配置文件也可以用.properties代替，不过为了其内容具有结构性，此处采用了yaml配置
配置各API分组下，分别有哪些服务需要暴露:

swagger:
  faced:
    open:
      groupName: 'OPEN前端'
      groupUrl: 'group=openApi'
      applications:
        - server1-application
        - server2-application

    admin:
      groupName: 'ADMIN后台'
      groupUrl: 'group=adminApi'
      applications:
        - server1-application
        - server2-application

微服务中配置的Docket的Group，需跟此处swagger.faced.**的key一致，
例子中两个分组：open，admin，那么微服务中也同样有两个分组（或其中之一，详情可看示例代码）

属性解释：
groupName: 定义了API分组的前缀名称，后面代码中使用“【】”括了起来使其更直观
groupUrl: 可以理解为访问doc需要的kv参数，此参数将被拼接到v2/api-docs?（swagger文档数据获取接口，GET类型）后进行使用
applications: 属性(list)配置了各分组下有哪些服务需要暴露，可以按需合理的进行暴露

2).SwaggerFacedBundleConfig配置（属性配置）：
SwaggerFacedBundleConfig将自定义的yaml配置注入到spring环境中，以便在swaggerResourceProvider中访问配置：

@Configuration
class SwaggerFacedBundleConfig {

    private val swaggerFacedBundleName = "swagger-faced.yml"

    @Bean
    fun swaggerFacedProperties(): PropertySourcesPlaceholderConfigurer? {
        val configurer = PropertySourcesPlaceholderConfigurer()
        val yaml = YamlPropertiesFactoryBean()
        yaml.setResources(ClassPathResource(swaggerFacedBundleName))
        configurer.setProperties(yaml.getObject()!!)
        return configurer
    }

    @Bean
    @ConfigurationProperties(prefix = "swagger.faced.open")
    fun open() = SwaggerFacedItem()

    @Bean
    @ConfigurationProperties(prefix = "swagger.faced.admin")
    fun admin() = SwaggerFacedItem()

}

open class SwaggerFacedItem {
    open lateinit var groupName: String
    open lateinit var groupUrl: String
    open lateinit var applications: List<String>
}

3).swaggerResourceProvider配置(实际聚合配置)：
此配置类利用Gateway的路由列表以及上述配置，对各微服务API文档的resource聚合进行提供

@Component
@Primary
class SwaggerResourceConfig : SwaggerResourcesProvider {

    val log = LoggerFactory.getLogger(SwaggerResourceConfig::class.java)

    @Autowired
    lateinit var swaggerFaced: List<SwaggerFacedItem>

    override fun get(): List<SwaggerResource> {
        val resources = mutableListOf<SwaggerResource>()
        NacosRouteDefinitionRepository.routeDefinitions.stream().forEach { route: RouteDefinition? ->
            route!!.predicates.stream()
                .filter { predicateDefinition: PredicateDefinition ->
                    "Path".equals(
                        predicateDefinition.name,
                        ignoreCase = true
                    )
                }
                .forEach { predicateDefinition: PredicateDefinition ->
                    addResource(
                        resources,
                        route,
                        predicateDefinition
                    )
                }
        }
        return resources.sortedBy { it.name }
    }

    private fun addResource(
        resources: MutableList<SwaggerResource>,
        route: RouteDefinition?,
        predicateDefinition: PredicateDefinition
    ) {
        for (facedItem in swaggerFaced) {
            facedItem.applications.filter { route!!.id.equals(it, ignoreCase = true) }.forEach { _ ->
                resources.add(
                    swaggerResource(
                        "【${facedItem.groupName}】" + route!!.id,//中括号更直观
                        predicateDefinition.args[NAME_PREFIX]!!
                            .replace("**", SWAGGER_DOC_PATH + facedItem.groupUrl)
                    )
                )
            }
        }
    }

    private fun swaggerResource(name: String, location: String): SwaggerResource {
        log.debug("name:{},location:{}", name, location)
        return SwaggerResource().apply {
            this.name = name
            this.location = location
            this.swaggerVersion = "2.0"
        }
    }

    companion object {
        private const val SWAGGER_DOC_PATH = "v2/api-docs?"
        private const val NAME_PREFIX = "pattern"
    }
}

其中NacosRouteDefinitionRepository.routeDefinitions为当前的provider提供了各微服务的路由信息列表，也可以根据项目实际情况替换为其他的微服务路由信息列表

三、定义资源访问控制器

暴露聚合文档的资源访问接口，此控制器的接口，在聚合文档的页面打开时被调用

/**
 * 自定义Swagger的各个配置节点
 * Created by macro on 2020/7/9.
 */
@RestController
class SwaggerHandler {

    @Autowired
    lateinit var swaggerResources: SwaggerResourcesProvider

    @Autowired(required = false)
    lateinit var securityConfiguration: SecurityConfiguration

    @Autowired(required = false)
    lateinit var uiConfiguration: UiConfiguration

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

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

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

至此聚合完成，是不是很简单？一个配置文件 两个配置类 一个controller

启动各微服务和gateway服务，可以通过：gateway访问地址/doc.html 来访问已经聚合的文档，本例中访问：http://localhost:2000/doc.html，即可看到聚合后的接口文档

四、效果对比

以我编写的实际例子来对比效果：
gateway的端口为2000，server1-application的端口为4001

未聚合文档前需要这样访问（含有具体微服务的前缀或端口）：
http://localhost:2000/server1-application/doc.html
或：
http://localhost:4001/doc.html

效果是这样的：
注意看左上角

聚合文档后，统一访问（无需微服务的前缀或具体端口）：
http://localhost:2000/doc.html
无需再访问微服务各自文档接口

另外这个组别（provider中get()方法的返回值：List<SwaggerResource>）可以自定义排序规则，当前实现默认使用了名称的自然顺序作为排序方式：

resources.sortedBy { it.name }

五、小结

以网关聚合的方式访问文档，对于比较依赖文档的人员，还是非常便捷的
不过比较遗憾的是不支持跨分组搜索，有兴趣的话可以拓展一下搜索相关的源码，这样就更方便了
聚合步骤也还是比较简单的，只需要跟文中操作步骤来就可以实现了
本文示例的代码地址：
springcloud-nacos-example tree:knif4j

欢迎在留言区发表你的看法意见与建议，共同探讨~~