【Gateway】网关集成Knife4j—swagger接口文档

news2024/11/26 9:56:40

文章目录

前言
一、相关配置
- 1.网关gateway配置
- - ①.网关增加配置 pom文件
  - ②.网关增加配置 SwaggerHandler
  - ③.网关增加配置 SwaggerResourceConfig
  - ④.网关增加配置 SwaggerConfig
- 2.网关过滤器
二、接口文档使用
- 1.访问文档
- 2.查看文档
总结

前言

在日常开发中是需要前后端联调的，接口文档可以实现接口字段等信息共享，swagger提供此功能，knife4j基于swagger进行增强处理。

提示：以下是本篇文章正文内容，下面案例可供参考

一、相关配置

1.网关gateway配置

①.网关增加配置 pom文件

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

②.网关增加配置 SwaggerHandler

package com.alpari.gateway.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;

import java.util.Optional;

@RestController
public class SwaggerHandler {

    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;

    @Autowired(required = false)
    private UiConfiguration uiConfiguration;

    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public 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)));
    }
}

③.网关增加配置 SwaggerResourceConfig

package com.alpari.gateway.config;

import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

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

@Component
@Primary
public class SwaggerResourceConfig implements SwaggerResourcesProvider {

    public static final String API_URI = "v2/api-docs";
    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;

    public SwaggerResourceConfig(RouteLocator routeLocator, GatewayProperties gatewayProperties) {
        this.routeLocator = routeLocator;
        this.gatewayProperties = gatewayProperties;
    }

    @Override
    public 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("**", API_URI))));
        });
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}

④.网关增加配置 SwaggerConfig

package com.alpari.gateway.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
        		.enable(ture)		// 是否启用 swagger
                .apiInfo(apiInfo())	// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .select()			// 设置哪些接口暴露，扫描所有
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：xx管理系统_接口文档")
                // 描述
                .description("描述：...")
                // 作者信息
                .contact("...")
                // 版本
                .version("版本号: ...")
                .build();
    }
}

2.网关过滤器

@Slf4j
@Order(-1)		// 保证请求必经此代码
@Component
public class GatewayFilter implements GlobalFilter {
	// 匿名可访问的 url，网关过滤器其他代码省略
    private static final List<String> ANONYMOUS_URI_LIST = new ArrayList<>();
    
    static {
        // 注意：生产环境下面这两个要注释掉，或者用开启停用状态来确保接口文档是否可匿名访问。
        ANONYMOUS_URI_LIST.add("/doc.html");
        ANONYMOUS_URI_LIST.add("/v2/api-docs");
    }
}

二、接口文档使用

前提是：你所开发的接口、实体类上等都配置了相关注解，如 controller 上有 @Api(tags = “用户”)，接口上有 @ApiOperation(“分页列表”)，实体类上有 @ApiModelProperty(value = “用户名称”) 等等相关注解，本篇文档不阐述这方面的知识。