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.

Note: You might encounter some of the issues that are described in the Table 1 when you use one or more of 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

Diagnosing the problem

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>`.