在本期 Swagger 焦點中，Tristan Sokol 是 Square 的開發人員倡導者，他將介紹其團隊如何使用 Swagger Codegen 產生 SDK。若要提交您自己的 Swagger 焦點主題，請按一下這裡。
Square 的開發人員平台團隊與大多數團隊略有不同。
我們不會為開發人員產品建構獨立的 API，而是專注於公開我們第一方產品使用的 API，為開發人員創造無縫的體驗。
我們有許多上游團隊是我們外部 API 的利害關係人，他們不斷希望公開新功能並進行改進。
這是在決定如何建構 SDK 時的重要因素；我們不希望我們的團隊成為瓶頸，導致產品團隊必須等待我們完成 SDK 更新才能發布新功能。
我們避免這種情況的主要方法是使用 SDK 產生。
SDK 產生
我們不手動撰寫每個 SDK（這不僅耗時、容易出錯，而且會減慢新功能發佈到 SDK 的速度），而是使用嚴重依賴 SDK 產生的流程。市面上有許多 SDK 產生方式，因此，如果您正在考慮為您的 SDK 採用類似的方法，請務必查看各種可能性，並找到適合您的方法。
我們偏好的方式是使用 OpenAPI 規格來定義我們的 API 端點，並使用 Swagger Codegen 以程式設計方式產生 SDK 的程式碼。
API 規格
我們使用 OpenAPI（以前稱為 Swagger 規格）標準來定義我們的 API。對我們而言，這是一個 JSON 檔案，其中定義了 URL、要發出的 HTTP 請求類型，以及要提供或預期從每個 API 端點取得的資訊類型。我們的規格由 3 個主要部分組成：一般資訊/中繼資料、路徑和模型。
一般資訊/中繼資料
規格的這一部分包含 API 的一些描述性資訊，例如您可以在哪裡找到授權資訊，或者應聯絡誰尋求協助。
"info": {
"version": "2.0",
"title": "Square Connect API",
"description": "Client library for accessing the Square Connect APIs",
"termsOfService": "https://connect.squareup.com/tos",
"contact": {
"name": "Square Developer Platform",
"email": "[email protected]",
"url": "https://squareup.com/developers"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
路徑
這些描述了 API 的個別端點（或 URL 路徑）。它描述了要發出的 HTTP 請求類型、應如何授權，以及您應在請求中新增哪些資訊，以及您應該預期會收到哪些資訊。
在下面的範例中，您可以看到它是一個 POST 請求，URL 中有幾個必要的參數，主體中還有另一個參數，並且您會收到一個 CreateRefundResponse 物件。
"/v2/locations/{location_id}/transactions/{transaction_id}/refund": {
"post": {
"tags": [
"Transactions"
],
"summary": "CreateRefund",
"operationId": "CreateRefund",
"description": "Initiates a refund for a previously charged tender.\n\nYou must issue a refund within 120 days of the associated payment. See\n(this article)[https://squareup.com/help/us/en/article/5060] for more information\non refund behavior.",
"x-oauthpermissions": [
"PAYMENTS_WRITE"
],
"security": [
{
"oauth2": [
"PAYMENTS_WRITE"
]
}
],
"parameters": [
{
"name": "location_id",
"description": "The ID of the original transaction\u0027s associated location.",
"type": "string",
"in": "path",
"required": true
},
{
"name": "transaction_id",
"description": "The ID of the original transaction that includes the tender to refund.",
"type": "string",
"in": "path",
"required": true
},
{
"name": "body",
"in": "body",
"required": true,
"description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.",
"schema": {
"$ref": "#/definitions/CreateRefundRequest"
}
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/CreateRefundResponse"
}
}
}
}
},
模型
模型描述 API 互動的不同物件。它們主要用於將 API 的 JSON 回應序列化為每種語言的原生物件。在以下範例中，CreateRefundResponse，您可以看到它包含幾個其他模型，以及描述，甚至還有回應的範例。
"CreateRefundResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/definitions/Error"
},
"description": "Any errors that occurred during the request."
},
"refund": {
"$ref": "#/definitions/Refund",
"description": "The created refund."
}
},
"description": "Defines the fields that are included in the response body of\na request to the [CreateRefund](#endpoint-createrefund) endpoint.\n\nOne of `errors` or `refund` is present in a given response (never both).",
"example": {
"refund": {
"id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
"location_id": "18YC4JDH91E1H",
"transaction_id": "TRANSACTION_ID",
"tender_id": "TENDER_ID",
"created_at": "2016-02-12T00:28:18Z",
"reason": "some reason",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"status": "PENDING"
}
},
"x-sq-sdk-sample-code": {
"python": "/sdk_samples/CreateRefund/CreateRefundResponse.python",
"csharp": "/sdk_samples/CreateRefund/CreateRefundResponse.csharp",
"php": "/sdk_samples/CreateRefund/CreateRefundResponse.php",
"ruby": "/sdk_samples/CreateRefund/CreateRefundResponse.ruby"
}
},
您可以在 GitHub 上的 Connect-API-Specification 存放庫中查看我們迄今最新版本的規格。
規格是我們產生流程的重要部分，因為它是關於我們的 API 如何運作的真實來源。當其他團隊想要擴展其 API、發布新 API 或只是增加模型描述的清晰度時，他們可以編輯這個單一檔案，並將其變更傳播到所有用戶端 SDK。
我們實際上是從描述內部服務到服務通訊的檔案中產生大部分規格，以實現更多流程自動化和更輕鬆的變更。
Swagger Codegen
現在我們已經準備好 API 的規格，我們如何將其轉換為面向用戶端的 SDK？答案是 Swagger Codegen。Swagger Codegen 是由 Smartbear 支援的開源專案（就像其他 Swagger 工具一樣），它會將您的 Open API 規格套用至一系列以不同語言建立 SDK 的範本，並加入一些組態。
範本
範本使用名為 mustache 的語言來定義其部分，並且在大多數情況下，看起來和讀起來都像是所需語言的檔案。下面這個是我們的 PHP SDK 範本的一部分。您可以看到，程式碼註解等有用的資訊也是自動產生的，因此最終的 SDK 可以擁有內建的文件、程式碼片段等等。
<?php
{{#models}}
{{#model}}
/**
* NOTE: This class is auto generated by the swagger code generator program.
* https://github.com/swagger-api/swagger-codegen
* Do not edit the class manually.
*/
namespace ;
use \ArrayAccess;
/**
* Class Doc Comment
*
* @category Class
* @package
* @author Square Inc.
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License v2
* @link https://squareup.com/developers
*/
class implements ArrayAccess
{
...
組態
這些實際上沒有那麼複雜，本質上是小型 json 檔案，其中描述了您的 SDK 的各個方面，通常是關於它如何融入相關的套件管理器。
{
"projectName": "square-connect",
"projectVersion": "2.8.0",
"projectDescription": "JavaScript client library for the Square Connect v2 API",
"projectLicenseName": "Apache-2.0",
"moduleName": "SquareConnect",
"usePromises": true,
"licenseName": "Apache 2.0"
}
由於 Codegen 專案非常活躍，我們實際上會針對我們支援的每個 SDK 檢查範本檔案的副本，並固定到特定的 Codegen 版本，以確保我們不會因為所有自動化而意外地將重大變更推送給我們的使用者。
您可以在與我們的規格檔案相同的存放庫中查看為 {Java、PHP、C#、Python、Ruby、JavaScript} SDK 提供支援的所有範本和組態檔案：Connect-API-Specification。
其他想法
我們的流程已經發展了很多，像 Travis CI 這樣的工具對流程產生了很大的影響。您可以使用 CI 和 CD 工具來使流程更加自動化，但請務必建立完善的測試涵蓋範圍，以協助防止意外變更悄悄進入您發佈的程式碼。
希望您喜歡了解我們的 SDK 產生流程。您也可以觀看我在 DevRelCon 上發表的相關演講，請按一下這裡。如果您想了解更多關於我們的 SDK 或 Square 的其他技術層面，請務必關注這個 部落格、我們的 Twitter 帳戶，並訂閱我們的 開發人員電子報！
這篇文章也刊登在 Square 的技術部落格上，請查看以了解更多資訊
Swagger 焦點是 Swagger 社群的成員與社群其他成員分享其見解和專案的機會。若要進一步了解如何讓您的文章成為焦點！