使用 Swagger 規格新增無法使用的端點

Composer 中的 ThingWorx 模型定義 > 建模 > 整合連接器 > 整合連接器先決條件 > 使用 OData 連接器或 SAPOData 連接器 > 使用 Swagger 規格新增無法使用的端點

例如，請考慮 OData 規格中的下列 EntityType 定義：

允許將 PrimaryContent 新增至指定 Document 的端點未包括在 ODataConnector 透過剖析 OData 規格產生的端點清單中。一般而言，對於 EntityType 的 NavigationProperty 定義，其後端系統所支援的任何端點皆不包括在連接器產生的清單中。因此，您應建立 Swagger 規格來定義這些端點，然後以 JSON 格式將此規格新增為 SwaggerJSON 內容的值。詳情請參閱使用 ODataConnector 或 SAPODataConnector。

在上述範例中，我們透過讀取 OData 規格來瞭解下列資訊：

• 端點的路徑格式為 /Documents('{ID}')/PrimaryContent，其中：

◦ Documents 是 entitySet 的名稱，其中將包含 Document 實體。

◦ ID 為 Document 的 Key，用於唯一識別 Document 實例。括住 ID 的大括號 {} 指示它是必需路徑參數的預留位置，應在以實際值取代預留位置來進行請求時提供。

◦ PrimaryContent 為 Document 的 NavigationProperty。

• PUT 為支援針對 Document 上載 PrimaryContent 的 HTTP 操作，因為 PrimaryContent 的類型為 ContentItem。ContentItem 的 HasStream 內容設定為 True。

• 應上載為 Document 的 PrimaryContent 的檔案為必需輸入項，並且為了成功執行請求，請求的 ContentType 應為 multipart/form-data。

• 執行端點的回應將為下列其中一個項目：

◦ JSON 物件，其結構描述完全符合 ContentItem 定義。

◦ 錯誤，用來指示無效請求。

在為端點建立 Swagger 規格定義之前，應使用諸如 Postman extension for Google Chrome 之類的應用程式來評估針對端點執行請求的所有需求。

在評估 Postman 中的需求之後，使用 Swagger 編輯器之類的工具來為端點建立定義。

1. 以一個空的 paths 物件啟動該編輯器。

2. 新增端點的路徑以及該路徑所支援的 HTTP 操作。在上述範例中，分別新增 "/Documents('{ID}')/PrimaryContent" 與 put。

3. 新增 ID (path 參數) 和 File (formData 參數) 的輸入參數定義。

4. 新增下列端點邏輯：consumes: [ multipart/form-data ], 與 produces: [ application/json ]。

5. 新增由端點產生的 HTTP 狀況碼所識別的回應。

例如：

◦ 成功操作 (HTTP 狀況碼 200) 會傳回結構描述符合 ContentItem 定義的 JSON 物件。我們透過 $ref 內容指示對 ContentItem 定義的參考。

◦ 無效請求 (HTTP 狀況碼 405)。

6. 新增 ContentItem 定義。如需瞭解結構描述，請參閱 OData 規格中的 ContentItem entityType 定義。

7. 為 PUT 操作提供 operationId 和摘要。

8. 當您在編輯器中解決了報告的錯誤，並已新增所需的路徑、操作與定義後，請將 Swagger 規格匯出為 JSON 檔案。

9. 複製已匯出 JSON 檔案的內容，並將其設定為 SwaggerJSON 內容的值。