本文主要用于介紹用戶CICD流程與API網(wǎng)關整合的通用方法實踐。該方法的核心是以swagger為橋接，通過API網(wǎng)關的ImportSwagger接口來完成您的API的自動創(chuàng)建和更新。
一、概述
API網(wǎng)關提供了完備的OpenAPI接口，用戶可以通過這些接口完成API網(wǎng)關的管理需要。用戶CICD集成API網(wǎng)關的核心，其實就是對API網(wǎng)關提供的管理接口進行封裝整合。
如下圖所示, 一個整合了API網(wǎng)關的通用CICD流程，主要有如下步驟：
步驟1：自動從您的API業(yè)務代碼中獲取swagger定義
步驟2：創(chuàng)建API分組
步驟3：通過API網(wǎng)關的OpenAPI導入API定義，并發(fā)布在不同的環(huán)境中
步驟4：對API進行各項額外配置
自動獲取Swagger定義
用戶開發(fā)時，可以自行整合一個API DOC框架（本文示例選擇的是SpringFox）到自己的后端服務中。這些框架一般對原有代碼都是無侵入的，所以接入相對方便。同時，API DOC框架隨后端服務啟動時，提供Swagger的獲取接口。API網(wǎng)關通過訪問這些接口，自動獲取Swagger定義
創(chuàng)建API分組
用戶可以在API網(wǎng)關控制臺手動創(chuàng)建分組，或者通過CreateApiGroup - 創(chuàng)建API分組創(chuàng)建分組。用戶創(chuàng)建分組后，可以進行綁定獨立域名以及綁定證書等操作。
通過OpenAPI導入API并發(fā)布
用戶通過集成API網(wǎng)關提供的ImportSwagger接口，并將Swagger獲取接口獲取的swagger數(shù)據(jù)作為參數(shù)，完成API的創(chuàng)建工作。在完成API在API網(wǎng)關的創(chuàng)建后，用戶可以將其發(fā)布到所需的環(huán)境。完成API的發(fā)布后，用戶即可訪問對應的服務。
額外配置
為了更靈活的滿足用戶個性化管理需求，API網(wǎng)關提供了豐富的插件。包括：流量控制插件，IP訪問控制插件，CORS插件以及JWT插件等。并根據(jù)需求選擇配置相關的插件，來豐富該接口的鑒權及管控能力。
二、實現(xiàn)示例
本章節(jié)對提供的示例代碼進行講解說明，本文的示例代碼僅提供了最基本的cicd場景，用戶可根據(jù)實際情況進行調整和擴充。
2.1 示例代碼
2.2 相關技術
本示例主要使用到的相關技術如下：
2.2.1 API網(wǎng)關相關鏈接
導入API網(wǎng)關的擴展Swagger定義介紹了如何配置可導入API網(wǎng)關的Swagger文件，API網(wǎng)關通過設計swagger支持的擴展內容，來完成標準swagger的直接導入和帶有用戶自定義配置的swagger導入。
ImportSwagger - 通過 Swagger 創(chuàng)建 API介紹了ImportSwagger接口。接口中主要參數(shù)為：
groupId: 用于存儲用戶swagger導入的API的分組ID。
data: 用戶的swagger文件 。
globalCondition: 用于用戶添加自定義的配置內容, 比如通過x-apigateway-backend-info標簽，加入用戶自定義后端的內容。
2.2.2 SpringFox
為了更直觀的展示如何運用swagger便捷的將后端服務同步到API網(wǎng)關中，本文提供了一個使用SpringFox庫的后端服務。 SpringFox是一個開源的API DOC的框架，它可以通過為服務Controller接口添加注釋的方式，便捷的形成swagger，并在服務運行時，提供獲取swagger的接口。
2.3 服務端自動生成swagger定義
服務端創(chuàng)建了一個基于springboot的極簡Web服務，用于展示一般用戶基于現(xiàn)有服務提供swagger的方法。
2.3.1 依賴庫
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>2.3.2 SpringFox的配置
SpringFox是對用戶原始服務相對友好的框架。用戶無需對現(xiàn)有的接口和模型類進行任何修改，僅需要增加一個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
啟動服務后, 可以通過訪問https://localhost:8080/swagger-ui.html來打開swagger UI來進行swagger提供的功能，具體查看官網(wǎng)swagger.io說明。
從截圖中我們可以看到, 示例代碼中的服務接口以及模型類均已被自動解析
如何獲取Swagger
為了可以接入用戶CICD的流程，獲取swagger內容的接口是必不可少的。用戶啟動服務后，用戶可以通過/v2/api-docs接口獲取swagger內容。
2.4 創(chuàng)建API分組
用戶可以通過以下方式創(chuàng)建分組
2.4.1 通過控制臺創(chuàng)建
用戶通過在API網(wǎng)關控制臺-分組管理界面創(chuàng)建分組。完成分組創(chuàng)建后，可以進入分組詳情頁，查看對應的分組ID及其他相關信息。
2.4.2 通過OpenAPI創(chuàng)建API分組
通過API網(wǎng)關的openapi提供的CreateApiGroup - 創(chuàng)建API分組接口完成APIGroup的創(chuàng)建。同時，用戶可以配合其他API完成用戶獨立域名以及綁定證書等其他操作。
2.5 ImportSwagger接口的使用
用戶能否實現(xiàn)基于API網(wǎng)關的CICD流程，其核心關鍵是：
是否有接口可以獲取swagger
標準swagger如何導入API網(wǎng)關
如2.2.2章節(jié)所介紹的內容. 我們已經(jīng)可以獲取描述后端服務所有接口和模型的swagger. 如何將標注的Swagger導入到API網(wǎng)關是我們本章節(jié)的重點.
2.5.1 基于API網(wǎng)關的Swagger擴展
API網(wǎng)關為了便于用戶體驗API網(wǎng)關的能力，支持將原生Swagger導入到API網(wǎng)關中。通過這種方式，API網(wǎng)關會自動創(chuàng)建基于Swagger的所有API，并且其默認后端為MOCK形式。
但是，用戶真實的CICD場景往往需要的是API網(wǎng)關創(chuàng)建的API最終真正的訪問到用戶的后端服務。這樣，就需要用戶進行后端服務信息的配置。但是，這些信息原生的swagger是不具備的，所以，API網(wǎng)關提供了基于Swagger的擴展。
基于Swagger的擴展主要包括：后端服務配置，后端參數(shù)配置，認證方式等API網(wǎng)關所必須的或者特有的內容的配置。這些拓展支持全局配置。同時，也支持每個API中單獨配置。 最終達到，用戶原生swagger配合API網(wǎng)關swagger擴展，真正實現(xiàn)滿足用戶生產環(huán)境所需的API配置。
本文示例中，僅使用了x-apigateway-backend-info擴展來進行說明。示例中，用戶的后端服務HTTP服務，我們假設其線上域名為www.aliyun.com。當然，后段地址也可以通過#環(huán)境變量#的形式進行配置。
我們在導入API網(wǎng)關的擴展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: 100002.5.2 通過ImportSwagger導入用戶原生Swagger
ImportSwagger是用戶原生Swagger導入到API網(wǎng)關的核心入口。這個接口有三個核心參數(shù)：
GroupId：用于指定存儲swagger導入API的分組。
data：用于指定用戶原生的Swagger。
globalCondition：用于傳入用戶的自定義配置，如通用后端服務地址。
Maven依賴
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-core</artifactId>
<version>4.5.0</version>
</dependency>
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-cloudapi</artifactId>
<version>4.9.3</version>
</dependency>獲取用戶原生swagger
上文已經(jīng)提及，用戶在完成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網(wǎng)關的Swagger擴展
正確的配置Swagger擴展是用戶通過導入Swagger創(chuàng)建滿足其需求的API的核心環(huán)節(jié). 這些基于API網(wǎng)關的swagger擴展可以通過ImportSwagger接口中的globalCondition參數(shù)傳入. globalCondition的格式為Json String。
key: 基于swagger的API網(wǎng)關擴展的名稱, 如：x-apigateway-backend-in
value: 對應swagger擴展的值。
示例代碼中，通過配置API的通用后端地址，實現(xiàn)導入API網(wǎng)關的API可以訪問到其真正的后端服務。
為了示例代碼的整潔，我們根據(jù)2.5.1中HTTP類型的后端服務說明，創(chuàng)建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;
}
}我們根據(jù)用戶的后端服務信息，完成globalCondition參數(shù)的賦值。
// 配置API網(wǎng)關所需的服務后端信息
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
上文中,我們已經(jīng)完成了Group的創(chuàng)建，原生Swagger的獲取以及GlobalCondition參數(shù)的創(chuàng)建。我們調用API網(wǎng)關openapi提供的ImportSwagger接口完成API的導入，并可以API網(wǎng)關控制臺查看導入結果。
2.6 部署API
用戶可以在API管理頁面選擇對應的分組，通過選擇需要發(fā)布的API進行發(fā)布.用戶通過發(fā)布使導入的API生效。
三、總結
自此, 如何將用戶后端服務的API接口快速的同步到API網(wǎng)關已經(jīng)完成。API網(wǎng)關致力于讓用戶專注于后端服務的開發(fā), 將認證、流控等通用切面功能交給API網(wǎng)關處理，結合ImportSwagger接口的使用，完成后端服務與API網(wǎng)關的聯(lián)動，大大減少了API網(wǎng)關的配置過程。同時，讓API網(wǎng)關的配置和管理集成到用戶的CICD流程中成為可能。