Limitations on OpenAPI specifications and tools

You might face some restrictions concerning the OpenAPI specifications and tools when you use the hosted transparent decision service (HTDS) through OpenAPI-based clients.

Symptoms

You might encounter an issue in some specific use cases due to an incorrect behavior in some of the OpenAPI reference tools.

Table 1 describes the issues that you might encounter with the following tools:

swagger-core Java™ library (embedded in the product): V1.5.10
Swagger Codegen code generation tool: V2.2.1
Swagger Editor: V2.10.3

New in 8.10.5 Operational Decision Manager currently uses OpenAPI 3.0. Table 2: OpenAPI 3.x data types and limitation shows the Java-type issues that you might encounter with the following tools:

swagger-core Java™ library (embedded in the product): V2.1.4
swagger-codegen code generation tool: V3.0.21

Note: The security definitions vary between OpenAPI 3.0 and 2.0. If you do not update the definitions, you might encounter an authentication error while invoking a ruleset in OpenAPI 3.0.

Diagnosing the problem

You cannot name ruleset parameters Request or Response.

Table 1. Data types and limitations
Data type	Limitation
`short` type	The OpenAPI specification has only `int32` and `int64` representations for `integer`, and standard integer numbers (`int` and `java.lang.Integer`) and long numbers (`long` and `java.lang.Long`) respectively for mapping. Short numbers (`short` and `java.lang.Short`) are mapped to `int32` and treated as regular integer numbers. As a consequence, when you use `short` or `java.lang.Short` in rule projects or decision services, clients or interfaces that are generated from the OpenAPI definition file provided by the HTDS allow you to input integer numbers instead of short numbers. Thus, entering a number bigger than the max value for `short` ends up in an execution error.
`password` data type annotation	Customizing Java XOM fields with the `@ApiModelProperty` annotation might be reflected on the OpenAPI definition file that is generated by the HTDS. In particular, you might use the datatype property to specify or override the type of the field of the Java object in OpenAPI. However, if you set `password` as a data type, the OpenAPI definition file might not be generated. You will see the following error: Unrecognized Type: [null] This problem is due to an incorrect behavior in the swagger-core Java library that is used for generating OpenAPI definition files. Avoid using the `password` data type. As a workaround, you can use a `String` field without an annotation (or at least without the `password` data type), and modify the generated OpenAPI definition file to specify `"format": "password"` in the corresponding field. It works with the Swagger Editor (the test form takes it into account, hiding characters as they are entered), and the Swagger Codegen tool can generate a client properly (the field is represented with a standard `String` type).
`binary` data type annotation	Similar to the `password` data type, a `String` field in a Java XOM can be annotated with the `@ApiModelProperty` annotation having `binary` as a data type property. Unlike the `password` data type, this `binary` data type does not prevent the OpenAPI definition file from being properly generated by the HTDS. However, if you use the Swagger Codegen tool to generate a Java client, the annotated field is represented as a `byte[]` field, which leads to a ruleset execution error at run time. In this particular use case, no such issue arises when you use the Swagger Editor.
`byte` type	When `byte` or `java.lang.Byte` is used as a XOM field or as a ruleset parameter, it becomes `byte[]` in a Java client that is generated by the Swagger Codegen tool, which leads to a ruleset execution error at run time. In this particular use case, no such issue arises when you use the Swagger Editor, since bytes are represented as strings, and the HTDS REST accepts and converts them to real bytes.
`arrays`	Arrays become lists when you use the Swagger Codegen tool to generate Java clients. For example, a field of type `String[]` becomes `List<String>`.

Table 2. OpenAPI 3.x data types and limitations
Data type	Limitation
`byte` type	When `byte` is used as a XOM field or a ruleset parameter, the `swagger V3 core` converts `byte` into swagger `StringSchema`, with the type `string` and the format `byte`. The `rang` limitation of the byte (`[-128, 127]`) is no longer respected. If the value that is used is outside the limitation, the result should be wrong.
`char` type	When `char` is used as a XOM field or a ruleset parameter, the `swagger V3 core` converts `char` into swagger `StringSchema`, with the type `string`. The length of the `char` is no longer respected. If the type is used with a string value length that is greater than 1, the execution throws an error.
`short` type	When `short` is used as a XOM field or a ruleset parameter, the `swagger V3 core` converts `short` into swagger `IntegerSchema`, with the type `integer` and the format `int32`. The `rang` of `int32` is `[-2147483648, 2147483647]`, so the `rang` limitation of the short `[-32768, 32767]` is no longer respected. If the value that is used is outside the short `rang`, the result should be wrong.