OpenAPI 规范和工具的限制

通过基于 OpenAPI 的客户机使用托管透明决策服务 (HTDS) 时，您可能会遇到一些与 OpenAPI 规范和工具有关的限制。

症状

由于某些 OpenAPI 参考工具中的不正确行为，您可能会在某些特定用例中遇到问题。

表 1 描述了使用以下工具时可能遇到的问题：

  • swagger-core Java™ 库 (嵌入在产品中): V1.5.10
  • Swagger Codegen 代码生成工具：V2.2.1
  • Swagger Editor：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 数据类型。

作为变通方法，可使用 String 字段而不使用注释（或者少不使用 password 数据类型），并修改生成的 OpenAPI 定义文件在对应的字段中指定 "format": "password"。 它与 Swagger 编辑器（测试表单将其考虑在内，并在输入字符时隐藏字符）配合使用，并且 Swagger Codegen 工具可以正确生成客户机（该字段以标准 String 类型表示）。
binary 数据类型注释 与 password 数据类型类似，可以使用具有 binary 作为数据类型属性的 @ApiModelProperty 注释来对 Java XOM 中的 String 字段进行注释。

与 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。 不再考虑字节的 rang 限制 ([-128, 127])。

如果使用的值超出限制，那么结果应该是错误的。
char 类型

当 char 用作 XOM 字段或规则集参数时， swagger V3 core 会将 char 转换为类型为 string的 Swagger StringSchema。 不再考虑 char 的长度。

如果该类型与长度大于 1 的字符串值配合使用，那么执行将抛出错误。
short 类型

当 short 用作 XOM 字段或规则集参数时， swagger V3 core 会将 short 转换为 swagger IntegerSchema，类型为 integer ，格式为 int32。 int32 的 rang 为 [-2147483648, 2147483647]，因此不再考虑 short 的 rang 限制 [-32768, 32767]。

如果所使用的值在 short rang 之外，那么结果应该是错误的。