Limitazioni delle specifiche e degli strumenti OpenAPI

Quando si utilizza il servizio decisionale trasparente ospitato (HTDS) tramite client OpenAPI-based, si possono incontrare alcune restrizioni relative alle specifiche e agli strumenti OpenAPI.

Sintomi

Potresti riscontrare un problema in alcuni casi di utilizzo specifici a causa di un comportamento non corretto in alcuni degli strumenti di riferimento OpenAPI .

La Tabella 1 descrive i problemi che potrebbero verificarsi con i seguenti strumenti:

Libreria Java™ swagger - core (integrata nel prodotto): V1.5.10
Strumento di generazione codice Swagger Codegen: V2.2.1
Editor Swagger: V2.10.3

Operational Decision Manager utilizza OpenAPI 3.0. Se si esegue l'aggiornamento da OpenAPI 2.0 a 3.0, le definizioni di sicurezza variano tra le versioni. Se non si aggiornano le definizioni, si potrebbe rilevare un errore di autenticazione durante il richiamo di una serie di regole in OpenAPI 3.0.

Tabella 2: OpenAPI 3.x tipi di dati e limitazione mostra i problemi di tipo Java che potresti riscontrare con i seguenti strumenti:

Libreria swagger - core Java™ (integrata nel prodotto): V2.1.4
Strumento di generazione del codice swagger-codegen: V3.0.21

Diagnosi del problema

Non è possibile denominare i parametri della serie di regole Request o Response.

Tabella 1. Tipi di dati e limitazioni
Tipo di dati	Limitazione
`short` tipo	La specifica OpenAPI ha solo rappresentazioni `int32` e `int64` per `integer`e numeri interi standard (`int` e `java.lang.Integer`) e numeri lunghi (`long` e `java.lang.Long`) rispettivamente per la mappatura. I numeri brevi (`short` e `java.lang.Short`) vengono associati a `int32` e trattati come numeri interi regolari. Di conseguenza, quando si utilizza `short` o `java.lang.Short` nei progetti di regole o nei servizi di decisione, i client o le interfacce generati dal file di definizione OpenAPI fornito da HTDS consentono di immettere numeri interi invece di numeri brevi. Quindi, l'immissione di un numero maggiore del valore massimo per `short` finisce in un errore di esecuzione.
Annotazione del tipo di dati `password`	La personalizzazione dei campi Java XOM con l'annotazione `@ApiModelProperty` potrebbe essere riflessa nel file di definizione OpenAPI generato da HTDS. In particolare, è possibile utilizzare la proprietà datatype per specificare o sovrascrivere il tipo di campo dell'oggetto Java in OpenAPI. Tuttavia, se si imposta `password` come tipo di dati, il file di definizione OpenAPI potrebbe non essere generato. Viene visualizzato il seguente errore: Tipo non riconosciuto: [ null] Questo problema è dovuto a un funzionamento non corretto nella libreria Java swagger-core utilizzata per generare i file di definizione OpenAPI . Evitare di utilizzare il tipo di dati `password` . Come soluzione temporanea, è possibile utilizzare un campo `String` senza un'annotazione (o almeno senza il tipo di dati `password` ) e modificare il file di definizione OpenAPI generato per specificare `"format": "password"` nel campo corrispondente. Funziona con l'editor Swagger (il modulo di test lo prende in considerazione, nascondendo i caratteri quando vengono immessi) e lo strumento Swagger Codegen può generare correttamente un client (il campo è rappresentato con un tipo `String` standard).
Annotazione del tipo di dati `binary`	In modo simile al tipo di dati `password` , un campo `String` in uno XOM Java può essere annotato con l'annotazione `@ApiModelProperty` che ha `binary` come proprietà del tipo di dati. A differenza del tipo di dati `password` , questo tipo di dati `binary` non impedisce al file di definizione OpenAPI di essere generato correttamente da HTDS. Tuttavia, se si utilizza lo strumento Swagger Codegen per generare un client Java, il campo annotato viene rappresentato come un campo `byte[]` , che porta a un errore di esecuzione della serie di regole al runtime. In questo particolare caso di utilizzo, non si verifica alcun problema quando si utilizza Swagger Editor.
`byte` tipo	Quando `byte` o `java.lang.Byte` viene utilizzato come un campo XOM o come un parametro della serie di regole, diventa `byte[]` in un client Java generato dallo strumento Swagger Codegen, che porta a un errore di esecuzione della serie di regole al runtime. In questo particolare caso di utilizzo, non si verifica alcun problema quando si utilizza l'editor Swagger, perché i byte vengono rappresentati come stringhe e HTDS REST li accetta e li converte in byte reali.
`arrays`	Gli array diventano elenchi quando si utilizza lo strumento Swagger Codegen per generare client Java. Ad esempio, un campo di tipo `String[]` diventa `List<String>`.

Tabella 2. OpenAPI 3.x tipi di dati e limitazioni
Tipo di dati	Limitazione
`byte` tipo	Quando `byte` viene utilizzato come un campo XOM o un parametro della serie di regole, `swagger V3 core` converte `byte` in swagger `StringSchema`, con il tipo `string` e il formato `byte`. La limitazione `rang` del byte (`[-128, 127]`) non viene più rispettata. Se il valore utilizzato non è compreso nella limitazione, il risultato dovrebbe essere errato.
`char` tipo	Quando `char` viene utilizzato come campo XOM o parametro della serie di regole, `swagger V3 core` converte `char` in swagger `StringSchema`, con il tipo `string`. La lunghezza di `char` non viene più rispettata. Se il tipo viene utilizzato con una lunghezza del valore di stringa maggiore di 1, l'esecuzione genera un errore.
`short` tipo	Quando `short` viene utilizzato come un campo XOM o un parametro della serie di regole, `swagger V3 core` converte `short` in swagger `IntegerSchema`, con il tipo `integer` e il formato `int32`. `rang` di `int32` è `[-2147483648, 2147483647]`, quindi la `rang` limitazione del breve `[-32768, 32767]` non viene più rispettata. Se il valore utilizzato è esterno al valore breve `rang`, il risultato dovrebbe essere errato.