knife4j实现微服务swagger文档聚合

使用knife4j实现分布式swagger文档聚合

在项目开发过程中,接口文档的使用是在所难免的,但是在微服务场景下,多个服务之间的swagger是分散的,虽然swagger提供了微服务的聚合方式,配置过于繁琐,加之swagger本身的功能比较少,而且ui布局也比较蛋痛,此处推荐一款新框架用于增强swagger以及实现微服务接口文档的聚合

knife4j官方文档:https://doc.xiaominfo.com/docs/

此处使用文档中提供的Spring Cloud Gateway网关聚合 | Knife4j (xiaominfo.com)方式

依赖引入

在整个项目的父pom中

    <properties><springdoc.version>2.0.2</springdoc.version><knife4j.version>4.0.0</knife4j.version></properties>
<dependencyManagement>
<!--            swagger--><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>${springdoc.version}</version></dependency><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webflux-api</artifactId><version>${springdoc.version}</version></dependency><!--knife4j 分布式接口文档聚合--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-gateway-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency>
</dependencyManagement>

gateway,因为gateway是基于webflux构建的因此需要导入的是webflux版本的swagger依赖

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-gateway-spring-boot-starter</artifactId>
</dependency>
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webflux-api</artifactId><scope>provided</scope>
</dependency>

服务server

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
</dependency>

配置文件编写

服务server:

springdoc:swagger-ui:path: /swaggertags-sorter: alphaoperations-sorter: alphaapi-docs:path: /服务名称/api-docs

gateway:

gateway:discovery:locator:enabled: true#此处是配置服务的路由routes:#        XXX模块- id: XXX-serveruri: lb://XXX-serverpredicates:- Path=/XXX/**knife4j:# 聚合swagger文档gateway:enable: trueroutes:#此处需要与上面的配置对应- name: XXX服务url: /XXX/api-docs?group=defaultservice-name: XXX-serverorder: 1