OpenAPI 規格和工具的限制

當您透過 OpenAPI 型用戶端使用代管的透通決策服務 (HTDS) 時，您可能會面臨一些關於 OpenAPI 規格和工具的限制。

症狀

在某些特定的使用案例中，您可能會因為某些 OpenAPI 參照工具中的不正確行為而遇到問題。

表 1 說明您使用下列工具時可能遇到的問題:

  • swagger-core Java™ 程式庫 (內嵌在產品中): V1.5.10
  • Swagger Codegen 程式碼產生工具: V2.2.1
  • Swagger 編輯器: V2.10.3

Operational Decision Manager 使用 OpenAPI 3.0。 如果您從 OpenAPI 2.0 升級至 3.0 ，各版本之間的安全定義會有所不同。 如果您未更新定義，在 OpenAPI 3.0 中呼叫規則集時可能會發生鑑別錯誤。

表 2 :OpenAPI 3.x 資料類型及限制 顯示您使用下列工具時可能遇到的 Java 類型問題:

  • swagger-core Java™ 程式庫 (內嵌在產品中): V2.1.4
  • swagger-codegen 程式碼產生工具: V3.0.21

診斷問題

您無法將規則集參數命名為 Request 或 Response。

表 1. 資料類型和限制
資料類型 限制
short 類型 OpenAPI 規格僅具有 integer的 int32 和 int64 表示法，以及分別用於對映的標準整數 (int 和 java.lang.Integer) 和長整數 (long 和 java.lang.Long)。

短數字 (short 和 java.lang.Short) 對映至 int32 並視為一般整數。

因此，當您在規則專案或決策服務中使用 short 或 java.lang.Short 時，從 HTDS 提供的 OpenAPI 定義檔產生的用戶端或介面可讓您輸入整數而非短數字。 因此，輸入大於 short 最大值的數字會導致執行錯誤。
password 資料類型註釋 使用 @ApiModelProperty 註釋來自訂 Java XOM 欄位可能會反映在 HTDS 所產生的 OpenAPI 定義檔中。
特別是，您可以使用 datatype 內容來指定或置換 OpenAPI 中 Java 物件的欄位類型。 不過，如果您將 password 設為資料類型，則可能不會產生 OpenAPI 定義檔。 您會看到下列錯誤:
無法辨識類型: [null]

此問題是因為 swagger-core Java 程式庫中用於產生 OpenAPI 定義檔的行為不正確。 避免使用 password 資料類型。

作為暫行解決方法，您可以使用不含註釋 (或至少不含 password 資料類型) 的 String 欄位，並修改產生的 OpenAPI 定義檔，以在對應欄位中指定 "format": "password" 。 它使用「Swagger 編輯器」(測試表單會將它納入考量，在輸入時隱藏字元) ，且 Swagger Codegen 工具可以適當地產生用戶端 (此欄位以標準 String 類型表示)。
binary 資料類型註釋 類似於 password 資料類型， Java XOM 中的 String 欄位可以用含有 binary 作為資料類型內容的 @ApiModelProperty 註釋來標註。

與 password 資料類型不同，此 binary 資料類型不會阻止 HTDS 適當地產生 OpenAPI 定義檔。

不過，如果您使用 Swagger Codegen 工具來產生 Java 用戶端，則標註的欄位會呈現為 byte[] 欄位，這會在執行時期導致規則集執行錯誤。

在這個特定使用案例中，當您使用「Swagger 編輯器」時，不會發生這類問題。
byte 類型 當使用 byte 或 java.lang.Byte 作為 XOM 欄位或規則集參數時，在 Swagger Codegen 工具所產生的 Java 用戶端中，它會變成 byte[] ，在執行時期會導致規則集執行錯誤。

在這個特定使用案例中，當您使用「Swagger 編輯器」時，不會發生這類問題，因為位元組是以字串來表示，而 HTDS REST 會接受它們，並將它們轉換成實際位元組。
arrays 當您使用 Swagger Codegen 工具來產生 Java 用戶端時，陣列會變成清單。

例如， String[] 類型的欄位會變成 List<String>。
表 2. OpenAPI 3.x 資料類型和限制
資料類型 限制
byte 類型

當使用 byte 作為 XOM 欄位或規則集參數時， swagger V3 core 會將 byte 轉換成 Swagger StringSchema，其類型為 string ，格式為 byte。 不再遵循位元組 ([-128, 127]) 的 rang 限制。

如果使用的值超出限制，則結果應該會錯誤。
char 類型

當使用 char 作為 XOM 欄位或規則集參數時， swagger V3 core 會將 char 轉換成 Swagger StringSchema，且類型為 string。 不再遵循 char 的長度。

如果使用類型的字串值長度大於 1 ，則執行會擲出錯誤。
short 類型

當使用 short 作為 XOM 欄位或規則集參數時， swagger V3 core 會將 short 轉換成 Swagger IntegerSchema，其類型為 integer ，格式為 int32。 int32 的 rang 是 [-2147483648, 2147483647]，因此不再遵循簡短 [-32768, 32767] 的 rang 限制。

如果所使用的值在簡短 rang之外，則結果應該會錯誤。