爲基於Spring Boot的微服務架構搭建一套自動化、集中管理的API文檔中心

簡介

本篇文章將闡述如何經過使用我開發Parliament，與Swagger、Keyhole Software提供的工具，搭建一套自動發佈、集中管理的API文檔中心。

背景介紹

Spring Boot與Sping Cloud等項目爲咱們搭建微服務架構提供了很大的便利。可是微服務架構的劣勢之一就是增長了治理的複雜度。
衆所周知，微服務架構中的各個應用是獨立開發、部署的。當微服務數量到達必定的數量後，集中管理API文檔的難度愈來愈大。
爲了減輕文檔壓力，不少Spring Boot項目集利用Swagger自動生成API描述頁面。然而Swagger並無解決API集中管控的問題，各個團隊必須清楚的知道其餘團隊的Swagger頁面地址，這勢必完成了維護成本。這也是Parliament項目初衷。

解決方案

我開發了一個簡單的API文檔中心服務器Parliament。Parliament集成了Swagger UI，用於顯示和調試API。
API信息發佈採用的是Keyhole Software開發的khs-spring-boot-publish-swagger-starter。須要注意的是原始的khs-spring-boot-publish-swagger-starter存在幾個bug，請暫時使用
我提供的版本。

背後的邏輯是：

1. 由Swagger2負責生成API描述，

2. 當Spring Boot應用每次啓動時，經過khs-spring-boot-publish-swagger-starter將API描述發送到Parliament服務器。

3. Parliament服務器存儲並整理API描述，並提供UI展現給各個團隊開發人員。

這樣咱們就擁有了一個集中的、自動化的API文檔中心。

開始搭建

在部署Parliament以前，咱們須要先安裝MongoDB。關於如何安裝、配置MongoDB不在此文章範圍。安裝好MongoDB後，進行以下步驟。

I. 部署Parliament

$git clone https://github.com/burnettzhong/parliament.git
$cd parliament

修改application.properties，配置數據源, 請將根據實際的MongoDB信息修改：

spring.data.mongodb.host = {MongoDB address}
spring.data.mongodb.database = {MongoDB database name}
spring.data.mongodb.port = {MongoDB port}

構建並啓動Parliament:

$mvn package && java -jar target/Parliament-1.0.0.jar

如今能夠打開http://localhost:8080/index.html，固然在基本是個空白頁面，由於咱們尚未發佈任何API信息到Parliament。

II. 讓Spring Boot應用發佈API信息

這裏咱們須要加入兩個依賴庫，一個是SpringFox的Swagger2，另外一個是khs-spring-boot-publish-swagger-startera。

注意：請不要使用來自Keyhole Software的khs-spring-boot-publish-swagger-starter，其中有兩個bug。只有他們合併咱們pull request，才能夠直接使用。

1. 在Keyhole Software在Maven公共庫中更新以前，咱們須要手動安裝個人版本(1.0.2)到本地Maven庫中:

   git clone https://github.com/burnettzho...
   cd khs-spring-boot-publish-swagger-starter
   mvn clean install

2. 在Spring Boot應用中增長Swagger2和khs-spring-boot-publish-swagger-starter依賴

   <dependency>

   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.6.1</version>

   </dependency>
   <dependency>

   <groupId>com.keyholesoftware</groupId>
   <artifactId>khs-spring-boot-publish-swagger-starter</artifactId>
   <version>1.0.2</version>

   </dependency>

3. 在application.yml或application.properties中配置Parliament地址：

   swagger:

   publish:
       publish-url: http://{Parliament server address}/swagger/publish/
       swagger-url: http://127.0.0.1:${server.port}/v2/api-docs

這裏有兩個地址，publish-url是咱們的Parliament部署地址,；swagger-url爲獲取API描述地址，通常來說都是本應用地址。

1. 最後經過註解配置Spring Boot應用：

   @EnableSwagger2
   @PublishSwagger
   public class ServiceApplication {

   ...

   }

@EnableSwagger2啓用Swagger2生成API描述，@PublishSwagger讓應用在啓動的時候將API描述JSON發佈到Parliament。

關於API描述的配置，Swagger2提供了很豐富的功能，請參考Springfox Reference Documentation。

至此，所有安裝部署結束。在啓動配置好的Spring Boot應用後，再打開http://localhost:8080/index.html就能夠看到咱們的API信息了。
Parliament根據API的base path進行分類，點擊某個base path能夠查看更詳細的API信息(這裏採用的是Swagger UI)。

後記

1. 若是須要，能夠將Parliament做爲一個微服務註冊到Euraka或者Zookeeper中。

2. 由於Parliament主要是在內網使用，目前沒有進行安全驗證。將來會引入對應用的認證，和用戶管理。

3. 將來Parliament還將增長API使用統計的功能，完善總體API治理。

歡迎關注並貢獻代碼到https://github.com/burnettzho...