本文主要介紹使用者CICD流程與API Gateway整合的通用方法實踐。該方法的核心是以Swagger為橋接,通過API Gateway的ImportSwagger介面來完成您的API的自動建立和更新。
一、概述
API Gateway提供了完備的OpenAPI介面,使用者可以通過這些介面完成API Gateway的管理需要。使用者CICD整合API Gateway的核心,其實就是對API Gateway提供的管理介面進行封裝整合。
一個整合了API Gateway的通用CICD流程,主要有如下步驟:
-
步驟1:自動從您的API業務代碼中擷取Swagger定義。
-
步驟2:建立API分組。
-
步驟3:通過API Gateway的OpenAPI匯入API定義,並發布在不同的環境中。
-
步驟4:對API進行各項額外配置。

自動擷取Swagger定義
使用者開發時,可以自行整合一個API DOC架構(本文樣本選擇的是SpringFox)到自己的後端服務中。這些架構一般對原有代碼都是無侵入的,所以接入相對方便。同時,API DOC架構隨後端服務啟動時,提供Swagger的擷取介面。API Gateway通過訪問這些介面,自動擷取Swagger定義。
建立API分組
使用者可以在API Gateway控制台手動建立分組,或者通過CreateApiGroup建立API分組。使用者建立API分組後,可以進行綁定獨立網域名稱以及綁定認證等操作。
通過OpenAPI匯入API並發布
使用者通過整合API Gateway提供的ImportSwagger介面,並將Swagger擷取介面資料作為參數,完成API的建立工作。在完成API在API Gateway的建立後,使用者可以將其發布到所需的環境。完成API的發布後,使用者即可訪問對應的服務。
額外配置
為了更靈活的滿足使用者個人化管理需求,API Gateway提供了豐富的外掛程式。包括:流量控制外掛程式,IP存取控制外掛程式,CORS外掛程式以及JWT外掛程式等。並根據需求選擇配置相關的外掛程式,來豐富該介面的鑒權及管控能力。
二、實現樣本
本章節對提供的範例程式碼進行講解說明,本文的範例程式碼僅提供了最基本的cicd情境,使用者可根據實際情況進行調整和擴充。
2.1 範例程式碼
2.2 相關技術
2.2.1 API Gateway相關連結
-
匯入API Gateway的擴充Swagger定義介紹了如何配置可匯入API Gateway的Swagger檔案,API Gateway通過設計Swagger支援的擴充內容,來完成標準Swagger的直接匯入和帶有使用者自訂配置的Swagger匯入。
-
通過 Swagger 建立 API介紹了ImportSwagger介面。介面中的主要參數為:
-
groupId: 用於儲存使用者Swagger匯入的API的分組ID。
-
data: 使用者的Swagger檔案內容 。
-
globalCondition: 用於使用者添加自訂的配置內容, 比如通過x-apigateway-backend-info標籤,加入使用者自訂後端的內容。
-
2.2.2 SpringFox
為了更直觀地展示如何運用Swagger便捷地將後端服務同步到API Gateway中,本文提供了一個使用SpringFox庫的後端服務。 SpringFox是一個開源的API DOC的架構,它可以通過為服務Controller介面添加註釋方式,便捷地形成Swagger,並在服務運行時,提供擷取Swagger介面。
2.3 服務端自動產生Swagger定義
服務端建立了一個基於Springboot的Web服務,用於展示一般使用者基於現有服務提供Swagger的方法。
2.3.1 依賴庫
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2.3.2 SpringFox的配置
SpringFox是對使用者原始服務相對友好的架構。使用者無需對現有的介面和模型類進行任何修改,僅需要增加一個SpringFox的配置類,即可完成Springfox架構的接入工作。在服務啟動後,該架構會自動解析Springboot web架構中的注釋,來自動產生Swagger中所需的服務資訊。同時,對於服務中引用的類進行解析,來產生Swagger所需的模型資訊。
SpringFox架構的配置項
本樣本中,配置項進行了如下核心設定:
-
指出文檔格式(Swagger2)
-
指出用於產生API DOC的包名
@Configuration
@EnableSwagger2
public class SpringFoxConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
}
如何擷取Swagger
為了接入使用者的CICD流程,擷取Swagger內容的介面是必不可少的。使用者啟動服務後,可以通過/v2/api-docs介面擷取Swagger內容。
訪問 http://localhost:8080/v2/api-docs 可擷取 Swagger 2.0 API 文檔的 JSON 響應,樣本如下:
{
"swagger": "2.0",
"info": {
"description": "Api Documentation",
"version": "1.0",
"title": "Api Documentation",
"termsOfService": "urn:tos",
"contact": {
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0"
}
},
"host": "localhost:8080",
"basePath": "/",
"tags": [
{
"name": "user-controller",
"description": "User Controller"
}
],
"paths": {
"/user": {
"get": {
"tags": [
"user-controller"
],
"summary": "getUser",
"operationId": "getUserUsingGET",
"produces": [
"*/*"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
},
2.4 建立API分組
使用者可以通過以下方式建立分組
2.4.1 通過控制台建立
使用者通過在API Gateway控制台的分組管理介面建立分組。完成分組建立後,可以進入分組詳情頁,查看對應的分組ID及其他相關資訊。
在API Gateway分組詳情頁面查看CiCdGroup分組的基本資料,記錄API分組ID(後續步驟需要使用)。頁面主要配置項包括:
-
地區:華東1 (杭州)
-
公網次層網域:僅供測試使用,每天有1000次訪問限制,正式環境請綁定獨立網域名稱
-
內網VPC網域名稱:未開通
-
執行個體類型:共用執行個體(傳統網路),分組QPS上限為500
-
HTTPS安全性原則:HTTPS2_TLS1_0
-
合法狀態:正常
2.4.2 通過OpenAPI建立API分組
通過API Gateway的openapi提供的建立API分組介面完成APIGroup的建立。同時,使用者可以配合其他API完成使用者獨立網域名稱以及綁定認證等其他動作。
2.5 ImportSwagger介面的使用
使用者能否實現基於API Gateway的CICD流程,其核心關鍵是:
-
是否有介面可以擷取Swagger
-
標準Swagger如何匯入API Gateway
如2.2.2章節所介紹的內容,我們已經可以擷取描述後端服務所有介面和模型的Swagger。如何將標註的Swagger匯入到API Gateway是我們本章節的重點。
2.5.1 基於API Gateway的Swagger擴充
API Gateway為了便於使用者體驗API Gateway的能力,支援將原生Swagger匯入到API Gateway中。通過這種方式,API Gateway會自動建立基於Swagger的所有API,並且其預設後端為MOCK形式。
但是,使用者真實的CICD情境往往需要的是API Gateway建立的API最終真正的訪問到使用者的後端服務。這樣,就需要使用者進行後端服務資訊的配置。但是,這些資訊原生的Swagger是不具備的,所以,API Gateway提供了基於Swagger的擴充。
基於Swagger的擴充主要包括:後端服務配置,後端參數配置,認證方式等API Gateway所必須的或者特有的內容的配置。這些擴充支援全域配置。同時,也支援每個API中單獨配置。 最終達到,使用者原生Swagger配合API GatewaySwagger擴充,真正實現滿足使用者生產環境所需的API配置。
本文樣本中,僅使用了x-apigateway-backend-info擴充來進行說明。樣本中,使用者的後端服務HTTP服務,我們假設其線上網域名稱為www.aliyun.com。當然,後段地址也可以通過#環境變數#的形式進行配置。
我們在匯入API Gateway的擴充Swagger定義一文中查看後端為HTTP類型的後端如何配置。當其中type和address為必填項,後端path和method為空白時,當前API的請求地址和HTTP方法,timeout預設為10000ms。
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
path: '/builtin/echo'
method: get
timeout: 10000
2.5.2 通過ImportSwagger匯入使用者原生Swagger
ImportSwagger是使用者原生Swagger匯入到API Gateway的核心入口。這個介面有三個核心參數:
-
GroupId:用於指定儲存Swagger匯入API的分組。
-
data:用於指定使用者原生的Swagger。
-
globalCondition:用於傳入使用者的自訂配置,如通用後端服務地址。
Maven依賴
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>alibabacloud-cloudapi20160714</artifactId>
<version>3.0.38</version>
</dependency>
擷取使用者原生swagger
上文已經提及,使用者在完成SpringFox架構引入和配置後,在服務啟動時,就會自動產生/v2/api-docs介面用於擷取描述後端服務的Swagger。
private String getSwaggerData(){
HttpURLConnection connection = null;
...
...
String result = null;
try {
URL url = new URL(swaggerApiDocUrl);
connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.connect();
...
...
} catch (Exception e) {
e.printStackTrace();
} finally {
...
...
connection.disconnect();
}
return result;
}
配置基於API Gateway的Swagger擴充
正確的配置Swagger擴充是使用者通過匯入Swagger建立滿足其需求的API的核心環節. 這些基於API Gateway的Swagger擴充可以通過ImportSwagger介面中的globalCondition參數傳入. globalCondition的格式為Json String。
-
key: 基於Swagger的API Gateway擴充的名稱, 如:x-apigateway-backend-in
-
value: 對應Swagger擴充的值。
範例程式碼中,通過配置API的通用後端地址,實現匯入API Gateway的API可以訪問到其真正的後端服務。
為了範例程式碼的整潔,我們根據2.5.1中HTTP類型的後端服務說明,建立SwaggerBackendInfoBase類,用於配置後端服務資訊。
public class SwaggerBackendInfoBase {
private String type;
private String address;
public String getType() {
return type;
}
public void setType(String type) {
this.type = type;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
}
我們根據使用者的後端服務資訊,完成globalCondition參數的賦值。
// 配置API Gateway所需的服務後端資訊
SwaggerBackendInfoBase info = new SwaggerBackendInfoBase();
info.setType("HTTP");
info.setAddress("http://www.aliyun.com");
// 將API的後端服務後端資訊
Map<String, String> globalCondition = new HashMap<>();
globalCondition.put("x-aliyun-apigateway-backend", JSON.toJSONString(info));
ImportSwagger
上文中,我們已經完成了Group的建立,原生Swagger的擷取以及GlobalCondition參數的建立。我們調用API Gatewayopenapi提供的ImportSwagger介面完成API的匯入,並可以API Gateway控制台查看匯入結果。
API 定義詳情頁(ID 為 364ea0e74bdd47b5ab05d5449232ae8a)顯示以下配置:
-
分組:CiCdGroup5,API名稱:getUserUsingGET,安全認證:阿里雲APP,類型:私人,簽名演算法:HmacSHA256
-
請求Path:
/user,協議:HTTP,HTTP Method:GET,請求模式:入參映射(過濾未知參數) -
後端服務類型:HTTP,後端服務地址:
http://www.aliyun.com/user,VPC通道:不使用,Mock:不使用,後端逾時:10000 ms -
傳回型別:JSON(application/json;charset=utf-8)
-
請求入參資訊、後端服務參數、常量參數、自訂系統參數均為空白
2.6 部署API
使用者可以在API管理頁面選擇對應的分組,通過選擇需要發布的API進行發布。使用者通過發布使匯入的API生效。在 API 列表頁面,勾選需要發布的 API(可通過列表左側的複選框全選),通過分組下拉篩選目標 API 分組,然後單擊列表下方的發布按鈕,即可批量發布所選 API。
三、總結
自此, 如何將使用者後端服務的API介面快速的同步到API Gateway已經完成。API Gateway致力於讓使用者專註於後端服務的開發, 將認證、流控等通用切面功能交給API Gateway處理,結合ImportSwagger介面的使用,完成後端服務與API Gateway的聯動,大大減少了API Gateway的配置過程。同時,讓API Gateway的配置和管理整合到使用者的CICD流程中成為可能。