SpringCloud Nacos + Gateway 聚合 swagger2/knife4j

SpringCloud Nacos + Gateway 聚合 swagger2/knife4j（本篇仅记录去掉Eureka，改为Nacos的过程）

官方文档

• https://nacos.io/zh-cn/docs/quick-start.html
• https://github.com/alibaba/spring-cloud-alibaba/wiki/版本说明

客户端

• https://github.com/alibaba/nacos/tags?after=1.3.1
• https://github.com/alibaba/nacos/releases/tag/1.3.1-beta

登录地址：

• http://你的ip:8848/nacos/index.html
• 登录名称：nacos
• 登录密码：nacos

涉及 eureka 的模块，都换成 nacos，重启服务之前，先 clean

环境说明

本次配置的是父子项目

• Spring Boot - 2.2.0.RELEASE
• Spring Cloud - Hoxton.RELEASE
• 注册中心 Nacos - 2.2.1.RELEASE
• 网关依赖 GateWay - 2.2.0.RELEASE

父级pom.xml

增加依赖 spring-cloud-alibaba-dependencies

    <modules>
        <module>doc</module>
        <module>system</module>
        <module>business</module>
    </modules>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
        <relativePath />
    </parent>
    
    <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- 集成 swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.10.5</version>
        </dependency>

        <!-- 集成 knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>
        
        <!-- 集成 nacos -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2.2.1.RELEASE</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        # 你自己的依赖包...
    </dependencies>
</dependencyManagement>

3、System 模块配置

system 依赖包 pom.xml

增加依赖 spring-cloud-starter-alibaba-nacos-discovery

<dependencies>
    <!-- 集成 nacos -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>
    
    <!-- 集成 swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    
    <!-- 集成 knife4j -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
    </dependency>
    
    # 你自己的依赖包...
</dependencies>

system 配置文件

注意区分 port、context-path

# application.properties

# 配置 server
server.port=9001
server.servlet.context-path=/system

# 配置 Nacos
spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

# 模块名称
spring.application.name=system

# 配置 knife4j（不写会报错）
knife4j.enable=true

system配置Java类

注意区分 groupName、basePackage

# Swagger2Config.java
@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {

    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public Swagger2Config(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean
    public Docket webApiConfig() {
        String groupName = "system";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.*.system"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("System 接口")
                .description("Restful 风格接口")
                .version("0.0.1")
                .build();
    }
}

启动文件，添加注解@EnableDiscoveryClient

# SystemApplication.java

@EnableDiscoveryClient
@SpringBootApplication
public class SystemApplication {
    public static void main(String[] args) {
        SpringApplication.run(SystemApplication.class, args);
    }
}

完成以上步骤，子项目集成 knife4j 完毕

• 访问：http://127.0.0.1:9001/system/doc.html
• 访问：http://127.0.0.1:9002/business/doc.html

4、Business 模块配置

• business 依赖包 pom.xml
• business 配置文件
• business 配置Java类
• 启动文件，添加注解

这几步参考system模块配置，此处省略…

5、Doc 模块配置

doc 依赖包 pom.xml

增加依赖 spring-cloud-starter-alibaba-nacos-discovery

<dependencies>
    <!-- 集成 nacos -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>

    <!-- 集成 knife4j -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
    </dependency>

    # 你自己的依赖包...
</dependencies>

doc 配置文件，nacos和 gateway 配置

# application.properties

# 配置 Server
server.port=9003
server.servlet.context-path=/

# 配置 Nacos
spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

# 模块名称
spring.application.name=doc

spring.cloud.gateway.discovery.locator.enabled=false
spring.cloud.gateway.discovery.locator.lowerCaseServiceId=true

# 路由转发
spring.cloud.gateway.routes[0].id=system
spring.cloud.gateway.routes[0].uri=lb://system
spring.cloud.gateway.routes[0].predicates[0].name=Path
spring.cloud.gateway.routes[0].predicates[0].args[0]=/system/**

# 路由转发
spring.cloud.gateway.routes[1].id=business
spring.cloud.gateway.routes[1].uri=lb://business
spring.cloud.gateway.routes[1].predicates[0].name=Path
spring.cloud.gateway.routes[1].predicates[0].args[0]=/business/**

doc配置 创建两个Java类

#SwaggerResourceConfig.java

@Component
@Primary
public class SwaggerResourceConfig implements SwaggerResourcesProvider {

    private static final Logger LOG = LoggerFactory.getLogger(SwaggerResourceConfig.class);

    // swagger2默认后缀
    private static final String Swagger2URL = "/v2/api-docs";

    // 网关名称
    @Value("${spring.application.name}")
    private String self;

    // 网关路由
    private final RouteLocator routeLocator;

    @Autowired
    public SwaggerResourceConfig(RouteLocator routeLocator) {
        this.routeLocator = routeLocator;
    }

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<SwaggerResource>();
        List<String> routeHosts = new ArrayList<>();

        routeLocator.getRoutes().filter(route -> route.getUri().getHost() != null)
                .filter(route -> !self.equals(route.getUri().getHost()))
                .subscribe(route -> routeHosts.add(route.getUri().getHost()));

        Set<String> dealed = new HashSet<>();

        // gateway.discovery.locator.enabled 必须为false
        // 否则gateway.routes项不生效
        
        routeHosts.forEach(instance -> {
            // 通过负载均衡寻找对应主机
            // serviceId/v2/api-docs
            String url = "/" + instance + Swagger2URL + "?group=" + instance;

            if (!dealed.contains(url)) {
                dealed.add(url);
                resources.add(swaggerResource(url, instance));
            }
        });

        return resources;
    }

    private SwaggerResource swaggerResource(String url, String name) {
        LOG.info("url:{}, instance:{}", url, name);
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setUrl(url);
        swaggerResource.setName(name);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}

# SwaggerHandler.java

@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({"", "/csrf", "/swagger-resources"})
    public Mono<ResponseEntity> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

启动文件，添加注解@EnableDiscoveryClient

@EnableDiscoveryClient
@SpringBootApplication
public class DocApplication {
    public static void main(String[] args) {
        SpringApplication.run(DocApplication.class, args);
    }
}

子项目 正常访问

• http://127.0.0.1:9001/system/doc.html
• http://127.0.0.1:9002/business/doc.html

通过网关 访问子项目

• http://127.0.0.1:9003/system/doc.html
• http://127.0.0.1:9003/business/doc.html

通过聚合 正常访问

• http://127.0.0.1:9003/doc.html