Spring Cloud Zuul中使用Swagger彙總API接口文檔

有很多讀者問過這樣的一個問題:雖然使用Swagger可以爲Spring MVC編寫的接口生成了API文檔,但是在微服務化之後,這些API文檔都離散在各個微服務中,是否有辦法將這些接口都整合到一個文檔中?之前給大家的回覆都只是簡單的說了個思路,昨天正好又有人問起,索性就舉個例子寫成博文供大家參考吧。

如果您還不瞭解Spring Cloud ZuulSwagger,建議優先閱讀下面兩篇,有一個初步的瞭解:

本文首發於:http://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/

準備工作

上面說了問題的場景是在微服務化之後,所以我們需要先構建兩個簡單的基於Spring Cloud的微服務,命名爲swagger-service-aswagger-service-b

下面只詳細描述一個服務的構建內容,另外一個只是名稱不同,如有疑問可以在文末查看詳細的代碼樣例。

  • 第一步:構建一個基礎的Spring Boot應用,在pom.xml中引入eureka的依賴、web模塊的依賴以及swagger的依賴(這裏使用了我們自己構建的starter,詳細可點擊查看)。主要內容如下:
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.10.RELEASE</version>
    <relativePath/>
</parent>

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

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

    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.0.RELEASE</version>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>Dalston.SR1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
  • 第二步:編寫應用主類:
@EnableSwagger2Doc
@EnableDiscoveryClient
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class).web(true).run(args);
    }

    @RestController
    class AaaController {
        @Autowired
        DiscoveryClient discoveryClient;

        @GetMapping("/service-a")
        public String dc() {
            String services = "Services: " + discoveryClient.getServices();
            System.out.println(services);
            return services;
        }
    }
}

其中,@EnableSwagger2Doc註解是我們自制Swagger Starter中提供的自定義註解,通過該註解會初始化默認的Swagger文檔設置。下面還創建了一個通過Spring MVC編寫的HTTP接口,用來後續在文檔中查看使用。

  • 第三步:設置配置文件內容:
spring.application.name=swagger-service-a
server.port=10010

eureka.client.serviceUrl.defaultZone=http://eureka.didispace.com/eureka/

swagger.base-package=com.didispace

其中,eureka服務端的配置採用了本站的公益eureka,大家可以通過http://eureka.didispace.com/查看詳細以及使用方法。另外,swagger.base-package參數制定了要生成文檔的package,只有com.didispace包下的Controller纔會被生成文檔。

注意:上面構建了swagger-service-a服務,swagger-service-b服務可以如法炮製,不再贅述。

構建API網關並整合Swagger

Spring Cloud構建微服務架構:服務網關(基礎)一文中,已經非常詳細的介紹過使用Spring Cloud Zuul構建網關的詳細步驟,這裏主要介紹在基礎網關之後,如何整合Swagger來彙總這些API文檔。

  • 第一步:在pom.xml中引入swagger的依賴,這裏同樣使用了我們自制的starter,所以主要的依賴包含下面這些:
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zuul</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>
  • 第二步:在應用主類中配置swagger,具體如下:
@EnableSwagger2Doc
@EnableZuulProxy
@SpringCloudApplication
public class Application {

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class).web(true).run(args);
    }

    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            resources.add(swaggerResource("service-a", "/swagger-service-a/v2/api-docs", "2.0"));
            resources.add(swaggerResource("service-b", "/swagger-service-b/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;
        }
    }
}

說明:@EnableSwagger2Doc上面說過是開啓Swagger功能的註解。這裏的核心是下面對SwaggerResourcesProvider的接口實現部分,通過SwaggerResource添加了多個文檔來源,按上面的配置,網關上Swagger會通過訪問/swagger-service-a/v2/api-docsswagger-service-b/v2/api-docs來加載兩個文檔內容,同時由於當前應用是Zuul構建的API網關,這兩個請求會被轉發到swagger-service-aswagger-service-b服務上的/v2/api-docs接口獲得到Swagger的JSON文檔,從而實現彙總加載內容。

測試驗證

將上面構建的兩個微服務以及API網關都啓動起來之後,訪問網關的swagger頁面,比如:http://localhost:11000/swagger-ui.html,此時可以看到如下圖所示的內容:

Spring-Cloud-Zuul-use-Swagger-API-doc-1.png

可以看到在分組選擇中就是當前配置的兩個服務的選項,選擇對應的服務名之後就會展示該服務的API文檔內容。

代碼示例

本文示例讀者可以通過查看下面倉庫的中的swagger-service-aswagger-service-bswagger-api-gateway三個項目:

如果您對這些感興趣,歡迎star、follow、收藏、轉發給予支持!

以下專題教程也許您會有興趣
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章