Spring Cloud Gateway集成聚合型Spring Boot API发布组件knife4j，增强Swagger

大家都知道，在前后端分离开发的时代，前后端接口对接是一项必不可少的工作。

可是，作为后端开发，怎么和前端更好的配合，才能让自己不心累、脑累，直接扔给前端一个后端开放api接口文档或者页面，让前端不用看着难受，也不用前端老问你，来愉快的合作呢？

原来可能我们一直用的是Swagger，不得不说Swagger是一个非常好的框架，自从它的出现，大大减少了我们对接的繁重工作。（以前我们开发可是经常要写开发接口文档的）

可是我们在用Swagger时，不管是Swagger本身，还是SwaggerUI，用起来其实不是那么的便捷，尤其是SwaggerUI，反正我用起来真的很是难受，也许是因为它不是我们国人开发的，所以操作方面根本没有我们国人的操作习惯设计。

幸好啊，我们国人也是很厉害的。

Knife4j这个东东，简直是及时雨，用起来丝滑的很。看看它的界面，是不是就是国人的思维设计？

有了这个东东，那么我们来研究一下，怎么让他来集成我们的Gateway，那么如何实现Gateway，可以查看我的上一篇文章。

轻量级的Spring Cloud Gateway实践，实现api和websocket转发https://blog.csdn.net/t610654893/article/details/137783310?spm=1001.2014.3001.5501

那么，我在这个项目基础上，实现Knife4j的集成实现。

首先，我来说一下我的整体项目结构：

--- 俩个主要的Spring Boot名
【app-server】前端接口服务
【manager-server】后端管理平台服务器接口
--- 微服网关、配置等平台服务
【cloud-server】
---【gateway-starter】路由套件 
--- 等等
【common-server】公共starter目录的服务
---【boot-starter】公共套件 
--- 等等

好，那么我们先从gateway着手来实现。首先pom.xml内引入：

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

在Gateway项目内，新增一个类集成SwaggerResourcesProvider来配置SwaggerProvider，获取Api-doc！

/*** <b>功能：</b>SWAGGER聚合服务<br>*/
@Slf4j
@Component
@Primary
@AllArgsConstructor
public class SwaggerResourceConfig implements SwaggerResourcesProvider {@Resourceprivate Environment env;private final RouteLocator routeLocator;private final GatewayProperties gatewayProperties;@Overridepublic List<SwaggerResource> get() {List<SwaggerResource> resources = new ArrayList<>();List<String> routes = new ArrayList<>();routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));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("**", "v3/api-docs"))));});return resources;}private SwaggerResource swaggerResource(String name, String location) {log.info("name:{},location:{}", name, location);SwaggerResource swaggerResource = new SwaggerResource();swaggerResource.setName(env.getProperty(name));swaggerResource.setLocation(location + "?group=KN");swaggerResource.setSwaggerVersion("3.0.3");return swaggerResource;}
}

为了能更好的实现界面的客观性，我们这里写了一个swaggerResource的方法，此方法主要是为了能更好的表达我们的Api接口是属于谁的。比如说我们在Gateway的配置内配置了：routes[0].id=lb://app-server，那么我们在配置后再加一个app-server=分组接口，那么在Knife4j内就可以更直观的选择属于app-server的项目API了。

我们这里主要还是你为了集成Swagger的内容，来完成Knife4j的前段实现。

因为Gateway里没有配置SwaggerConfig，而运行Swagger-ui又需要依赖一些接口，所以我们还需要自己来实现swagger-resource端点。

这里其实也很简单，我们再新建一个类，来完成我们对swagger-resource的实现。

/*** <b>功能：</b>SWAGGER聚合服务<br>*/
@RestController
public class SwaggerHandler {@Autowired(required = false)private SecurityConfiguration securityConfiguration;@Autowired(required = false)private UiConfiguration uiConfiguration;private final SwaggerResourcesProvider swaggerResources;@Autowiredpublic SwaggerHandler(SwaggerResourcesProvider swaggerResources) {this.swaggerResources = swaggerResources;}@GetMapping("/swagger-resources/configuration/security")public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {return Mono.just(new ResponseEntity<>(Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));}@GetMapping("/swagger-resources/configuration/ui")public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {return Mono.just(new ResponseEntity<>(Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));}@GetMapping("/swagger-resources")public Mono<ResponseEntity> swaggerResources() {return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));}@GetMapping("/api")@SentinelResource("api")public Set<ApiDefinition> apiRules() {return GatewayApiDefinitionManager.getApiDefinitions();}@GetMapping("/gateway")@SentinelResource("gateway")public Set<GatewayFlowRule> apiGateway() {return GatewayRuleManager.getRules();}@GetMapping("/flow")@SentinelResource("flow")public List<FlowRule> apiFlow() {return FlowRuleManager.getRules();}
}

Gateway端接口已经配置完成。接下来配置实现客户端，由于我的工程俩个server都引入了boot-server，所以这里我只在boot-server内实现即可。

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-micro-spring-boot-starter</artifactId><version>3.0.3</version>
</dependency>

客户端服务基本也就是按照Swagger的配置写config即可。这样更加方便我们以Swagger为基础更增强我们的api接口发布。为了更详尽的使用，我们一一实现。

增加Swagger 配置类

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfiguration {@Resourceprivate SwaggerProperties swaggerProperties;@Beanpublic Docket createRestApi() {Boolean enable = swaggerProperties.getEnable();String tryHost = swaggerProperties.getTryHost();return new Docket(DocumentationType.OAS_30).groupName("KN")// 定义是否开启swagger，false为关闭，可以通过变量控制.enable(enable)// 将api的元信息设置为包含在json ResourceListing响应中。.apiInfo(apiInfo())// 接口调试地址.host(tryHost)// 选择哪些接口作为swagger的doc发布.select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.regex("/api/.*")).build();}/*** <b>功能描述：</b>API 页面上半部分展示信息<br>* <b>修订记录：</b><br>* <li>20201225&nbsp;&nbsp;|&nbsp;&nbsp;田星亮&nbsp;&nbsp;|&nbsp;&nbsp;创建方法</li><br>*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(swaggerProperties.getApplicationName()).description(swaggerProperties.getApplicationDescription()).termsOfServiceUrl("https://www.kn.com/").contact(new Contact("KN", null, "admin@kn.com")).version(swaggerProperties.getApplicationVersion()).build();}
}

这里我们再增强一下，使我们的接口更符合api接口规范，给API头增加名为Token的头，在createRestApi方法Docket实现内增加俩个方法后缀，并付上实现：

.build()
// 授权信息设置，必要的header token等认证信息
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());

 /*** <b>功能描述：</b>设置授权信息<br>*/private List<SecurityScheme> securitySchemes() {return Collections.singletonList(new ApiKey("token", "token", In.HEADER.toValue()));}/*** <b>功能描述：</b>授权信息全局应用<br>*/private List<SecurityContext> securityContexts() {return Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("token", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build());}

上方内配置项详解，完成灵活调用

@Data
@ConfigurationProperties("swagger")
public class SwaggerProperties {/*** 是否开启swagger，生产环境一般关闭，所以这里定义一个变量*/private Boolean enable;/*** 项目应用名*/private String applicationName;/*** 项目版本信息*/private String applicationVersion;/*** 项目描述信息*/private String applicationDescription;/*** 接口调试地址*/private String tryHost;
}

至此，我们配置完成，打开Gateway所属的端口链接即可完成Knife4j的访问。Knife4j的配置内还有一些高级项配置，大家按照自己需要增强哦，比如说api排序这个我就很喜欢。