SpringCloud系列之三---Zuul網關整合Swaagger2管理API

前言

本篇文章主要介紹的是Zuul網關整合Swaagger2管理API。

實作過程需要先建立eureka服務端，再建立多個微服務項目，每個微服務項目整合swagger2，形成接口文檔，并且每個微服務需要注冊到eureka注冊中心。再建立zuul網關對所有的swagger進行管理,zuul網關也需要作為eureka用戶端注冊到注冊中心。

GitHub源碼連結位于文章底部。

1.eureka服務端

首先建立eureka注冊中心，因為這隻是一個注冊中心，是以隻需要引入eureka服務端jar即可。

1.1 pom依賴

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
    </dependency>
</dependencies>
           

1.2 配置檔案

生産環境中需要開啟自我保護機制，删除eureka.server

server:
  port: 8100

spring:
  application:
    name: eureka-server

#eureka基本配置資訊
eureka:
  client:
    service-url:
      #Eureka 用戶端與 Eureka 服務端進行互動的位址
      defaultZone: http://127.0.0.1:${server.port}/eureka
    #是否将自己注冊到Eureka服務中,本身就是注冊中心是以無需注冊
    register-with-eureka: false
    #是否從Eureka中檢索注冊資訊,本身就是注冊中心是以無需檢索
    fetch-registry: false
  server:
    # 測試時關閉自我保護機制，保證不可用服務及時踢出
    enable-self-preservation: false
    ##剔除失效服務間隔
    eviction-interval-timer-in-ms: 2000
           

1.3 啟動類

在方法上添加eureka服務端注解EnableEurekaServer。

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

啟動以後通路 127.0.0.1:8100 即可打開eureka注冊中心可視化界面。

2.建立使用者服務和郵件服務兩個項目

建立使用者服務和郵件服務兩個項目，這兩個服務需要作為eureka用戶端，注冊到eureka注冊中心，兩個服務都需要整合swagger2，使用者服務需要使用Feign調用郵件服務。

2.1郵件服務引入依賴

郵件服務作為eureka用戶端，以及需要整合swagger2，是以隻需要引入兩個依賴

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
    </dependency>
    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.0.RELEASE</version>
    </dependency>
</dependencies>
           

2.2郵件服務配置檔案

配置檔案包括配置端口、應用名、eureka用戶端資訊、swagger配置資訊，需要注意swagger配置了controller層所在的包，它會檢測包中swagger相關注解。

server:
  port: 8200

spring:
  application:
    name: app-email

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8100/eureka
  server:
    # 測試時關閉自我保護機制，保證不可用服務及時踢出
    enable-self-preservation: false
    ##剔除失效服務間隔
    eviction-interval-timer-in-ms: 2000

####swagger相關配置
swagger:
  base-package: com.lxg.controller
  title: SpringCloud2.x建構微服務項目-郵件服務接口
  description: 郵件有關的服務
  version: 1.1
  terms-of-service-url: www.lxgblog.com
  contact:
    name: 李先國
    email: [email protected]
           

2.3 郵件服務controller層

在郵件服務中寫一個擷取郵件資訊的Get接口，

Api(tags = "郵件微服務")

是swagger的注解，它為controller命名，swagger其他注解見另一篇文章https://www.lxgblog.com/article/1576055897

@RestController
@Api(tags = "郵件微服務")
public class EmailController {
    @GetMapping("/email")
    public String email() {
        return "[email protected]";
    }
}
           

2.4 郵件服務啟動類

EnableSwagger2Doc注解開啟swagger，EnableEurekaClient啟動eureka用戶端

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

2.5 使用者服務引入依賴

使用者服務作為eureka用戶端，需要整合swagger2，并且它需要通過Feign遠端調用郵件服務，是以是三個依賴。

<dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
        </dependency>
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>
    </dependencies>
           

2.6 使用者服務配置檔案

配置檔案包括配置端口、應用名、eureka用戶端資訊、swagger配置資訊，需要注意swagger配置了controller層所在的包，它會檢測包中swagger相關注解。

server:
  port: 8300

spring:
  application:
    name: app-user

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8100/eureka
  server:
    # 測試時關閉自我保護機制，保證不可用服務及時踢出
    enable-self-preservation: false
    ##剔除失效服務間隔
    eviction-interval-timer-in-ms: 2000

####swagger相關配置
swagger:
  base-package: com.lxg.controller
  title: SpringCloud2.x建構微服務項目-使用者服務接口
  description: 使用者有關的服務
  version: 1.1
  terms-of-service-url: www.lxgblog.com
  contact:
    name: 李先國
    email: [email protected]
           

2.7 使用者服務的Feign

使用者服務需要調用郵件服務，是以需要建立一個EmailFeign的interface，使用FeignClient注解，值為郵件服務的應用名，這在郵件服務的配置檔案中有，然後将郵件服務中需要被調用的接口拷貝到這裡（包括方法上的注解）

@FeignClient("app-email")
public interface EmailFeign {
    @GetMapping("/email")
    public String email();
}
           

2.8 使用者服務的controller層

在使用者服務中寫一個調用郵件服務的Get接口，

Api(tags = "使用者微服務")

是swagger的注解，它為controller命名，swagger其他注解見另一篇文章https://www.lxgblog.com/article/1576055897 ，同時将郵件Feign注入進來，通過它調用的方法其實是調用的遠端服務。

@RestController
@Api(tags = "使用者微服務")
public class UserController {
    @Autowired
    private EmailFeign emailFeign;

    @GetMapping("/user")
    public String user() {
        return "使用者擷取郵箱："+emailFeign.email();
    }
}
           

2.9 使用者服務啟動類

EnableSwagger2Doc注解開啟swagger，EnableEurekaClient啟動eureka用戶端，EnableFeignClients啟動Feign用戶端。

@SpringBootApplication
@EnableEurekaClient
@EnableSwagger2Doc
@EnableFeignClients
public class UserApp {
    public static void main(String[] args) {
        SpringApplication.run(UserApp.class, args);
    }
}
           

啟動這兩個服務後，直接調用郵件服務中的接口：

通過調用使用者服務的接口調用郵件服務：

分别通路127.0.0.1:8200/swagger-ui.html,127.0.0.1:8300/swagger-ui.html，也可以使用swagger測試上述接口：

3.建立Zuul網關整合兩個服務的swagger

3.1 Zuul網關引入依賴

它需要作為eureka服務端注入到eureka注冊中心，作為zuul網關，整合swagger，是以需要引入如下三個依賴：

<dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
        </dependency>
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>
    </dependencies>
           

3.2 Zuul的配置檔案

配置檔案包括了端口号、服務名稱、eureka用戶端配置，網關反向代理配置。zuul.routes.api-user中的api.user可以任意命名，隻要不重複即可，這裡隻作為區分。通路網關項目+path的值+相關服務接口的URI，就相當于直接通路對應服務的接口。

###服務啟動端口号
server:
  port: 80
###服務名稱(服務注冊到eureka名稱)
spring:
  application:
    name: app-zuul
###服務注冊到eureka位址
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8100/eureka


### 配置網關反向代理
zuul:
  routes:
    api-user:
      path: /api-user/**
      serviceId: app-user
    api-email:
      path: /api-email/**
      serviceId: app-email

           

3.3 Zuul的啟動類

在啟動類上加入EnableEurekaClient注解開啟eureka用戶端，EnableZuulProxy注解開啟網關，EnableSwagger2Doc注解開啟swagger。

在啟動類中整合了不同服務中的swagger

@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class AppZuul {
    public static void main(String[] args) {
        SpringApplication.run(AppZuul.class, args);
    }

    // 添加文檔來源
    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            resources.add(swaggerResource("app-user", "/app-user/v2/api-docs", "2.0"));
            resources.add(swaggerResource("app-email", "/app-email/v2/api-docs", "2.0"));
            return resources;
        }

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

    }
}
           

啟動網關服務後，通路127.0.0.1/swagger-ui.html

因為配置的是80端口，是以浏覽器通路會省略80端口

通過網關通路郵件服務的接口，127.0.0.1/api-email/email和上面的127.0.0.1:8200/email是一樣的

通過網關通路使用者服務的接口去調用郵件服務的接口，127.0.0.1/api-user/email和上面的127.0.0.1:8300/user是一樣的

這是由zuul配置檔案中反向代理配置的。

本文GitHub源碼：https://github.com/lixianguo5097/springcloud/tree/master/springcloud-springcloud-zuul-swagger2

CSDN：https://blog.csdn.net/qq_27682773

簡書：https://www.jianshu.com/u/e99381e6886e

部落格園：https://www.cnblogs.com/lixianguo