系列学习 Swagger 之第 2 篇 —— SpringCloud Gateway 整合 Swagger（完结）

 

OK，这一篇博客继续讲解 Swagger 整合到 SpringCloud Gateway。

我们使用 swagger-spring-boot-starter 版本，可以查看 Maven 官网：https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter

我们搭建一个完整的 demo，包括注册中心 Eureka（端口8080），网关 Gateway（端口80），2个微服务：产品微服务（端口1001）、订单微服务（端口1002）。代码结构如图：

 

这里只说重点部分，可以先下载代码：https://pan.baidu.com/s/17XKJEwNLpcxf-7PtmbOU_Q  提取码：f7b3

 

最外层 pom.xml 配置如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.study</groupId>
    <artifactId>swagger-gateway</artifactId>
    <packaging>pom</packaging>
    <version>1.0-SNAPSHOT</version>
    <modules>
        <module>eureka-server</module>
        <module>gateway-server</module>
        <module>product-server</module>
        <module>order-server</module>
    </modules>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
    </parent>

    <properties>
        <!-- 配置 Swagger 版本 -->
        <swagger.version>1.9.0.RELEASE</swagger.version>
    </properties>

    <dependencies>
        <!--Spring boot 集成包-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- swagger-start 依赖。https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>${swagger.version}</version>
        </dependency>

        <!-- lombok 依赖 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Hoxton.SR2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

</project>

 

然后说一下产品服务的代码，订单服务是一样的，不赘述。

product-server 的 pom.xml 配置：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>swagger-gateway</artifactId>
        <groupId>com.study</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>product-server</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

</project>

实体类：

package com.study.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 5:45
 */
@Data
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor(staticName = "of")
@Builder
@ApiModel(description = "产品实体类")
public class ProductEntity {

    @ApiModelProperty(value = "产品ID")
    private Integer productId;

    @ApiModelProperty(value = "产品名称")
    private String productName;


}

控制层：只需要添加注解 @EnableSwagger2Doc 即可，因为 SpringBoot 已经帮我们整合配置了，不需要 SwaggerConfig 类！

package com.study.controller;

import com.spring4all.swagger.EnableSwagger2Doc;
import com.study.entity.ProductEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 5:45
 */
@RestController
@Api(tags = "产品信息管理 API 接口文档")
@RequestMapping("/api/product")
@EnableSwagger2Doc //SpringBoot 已经整合好 swagger 的相关配置了
public class ProductController {

    @PostMapping("/getProductInfo")
    @ApiOperation(value = "查询产品信息接口", notes = "这是一段方法的描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "productId", value = "产品Id", required = false, dataType = "Integer"),
            @ApiImplicitParam(name = "productName", value = "产品名称", required = true, dataType = "String")
    })
    public ProductEntity getInfo(@RequestParam(value = "productId",required = false) Integer productId,
                                 @RequestParam("productName") String productName) {
        ProductEntity productEntity = new ProductEntity();
        productEntity.setProductId(123);
        productEntity.setProductName("霸王防脱洗发液");
        return productEntity;
    }
}

如果想自定义配置信息，怎么办？可以自定义配置类 SwaggerConfig，也可以写在配置文件里，如下：

application.yml 代码

server:
  port: 1001

eureka:
  instance:
    hostname: 127.0.0.1
  client:
    serviceUrl:
      defaultZone: http://${eureka.instance.hostname}:8080/eureka/

spring:
  application:
    name: product-server

# swagger 相关配置
swagger:
  title: "无限商城-产品模块"
  description: "让天下没有难写的代码"
  version: V1.0
  enabled: true

 

然后到网关服务的代码

pom.xml 配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>swagger-gateway</artifactId>
        <groupId>com.study</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>gateway-server</artifactId>

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

</project>

配置类 SwaggerConfig，需要实现接口：springfox.documentation.swagger.web.SwaggerResourcesProvider

package com.study.config;

import lombok.AllArgsConstructor;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
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;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-07 上午 1:29
 */
@Component
@Primary
@AllArgsConstructor
public class SwaggerConfig implements SwaggerResourcesProvider {

    public static final String API_URI = "/v2/api-docs";

    private final RouteLocator routeLocator;

    private final GatewayProperties gatewayProperties;


    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        //取出gateway的route
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        //结合配置的route-路径(Path)，和route过滤，只获取有效的route节点
        gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
                .forEach(routeDefinition -> routeDefinition.getPredicates().stream()
                        .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                        .forEach(predicateDefinition -> resources.add(swaggerResource(routeDefinition.getId(),
                                "/"+routeDefinition.getId()+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;

    }

}

控制层 controller

package com.study.controller;

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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;

import java.util.Optional;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-07 上午 1:31
 */
@RestController
@RequestMapping("/swagger-resources")
public class SwaggerController {

    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;

    @Autowired(required = false)
    private UiConfiguration uiConfiguration;

    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public SwaggerController(SwaggerResourcesProvider swaggerResources) {
        this.swaggerResources = swaggerResources;
    }

    @GetMapping("/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    @GetMapping("/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    @GetMapping("")
    public Mono<ResponseEntity> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

重点来了，application.yml 配置

server:
  port: 80

eureka:
  instance:
    hostname: 127.0.0.1
  client:
    serviceUrl:
      defaultZone: http://${eureka.instance.hostname}:8080/eureka/


spring:
  application:
    name: gateway-server
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true  #表明gateway开启服务注册和发现的功能， 动态路由
          lowerCaseServiceId: true

      routes:
      # 路由的 ID，没有固定规则但要求唯一，建议配合服务名
      # 产品微服务路由
      - id: product-server
        # 根据服务名称从注册中心获取服务地址
        uri: lb://product-server
        # 断言
        predicates:
        - Path=/**

      # 产品微服务路由
      - id: order-server
        # 根据服务名称从注册中心获取服务地址
        uri: lb://order-server
        # 断言
        predicates:
        - Path=/**

说明：

1、配置动态路由，否则会报错：Failed to load API definition. 找不到 API 的定义

2、为每个微服务配置路由规则 routes，否则报错： 😱 Could not render e, see the console.

网上说还需要配置过滤器，在 swagger-spring-boot-starter 1.9.0 版本是不需要的。

        # 配置过滤器
        filters:
          # 去掉路由前缀，访问 localhost:1001/product/v2/api 转发的就是 localhost:1001/v2/api
          # 1 : 代表剥离路径的个数
          - StripPrefix=1

OK，我们启动微服务测试：

可以先测试产品微服务的 swagger 是否正常：http://127.0.0.1:1001/swagger-ui.html

再测试走网关的情况是否正常：http://127.0.0.1/swagger-ui.html

 

 

老铁们，没毛病！

OK，Swagger 整合 Gateway 讲解到这。

本篇博客代码地址：https://pan.baidu.com/s/17XKJEwNLpcxf-7PtmbOU_Q  提取码：f7b3