# Supporto per OpenAPI Specification 3.0

Progetta un'API con OpenAPI Specification (OAS) 3.0 utilizzando i contratti API.

OpenAPI Specification 3.0 introduce nuove funzionalità, offrendo maggiore espressività e produttività ai progettisti di API.

Per ulteriori informazioni su OpenAPI, consulta la [documentazione di Swagger](https://swagger.io/docs/specification/about/).

## Componenti

I componenti consentono di riutilizzare vari elementi all'interno di un'API. Questi elementi possono essere:

* Variabili di percorso
* Parametri query
* Intestazioni
* Risposte

## Combinazioni

Le combinazioni consentono di creare un nuovo tipo di dati combinando diversi altri tipi di dati. API Contracts supporta due tipi di combinazioni:

* La composizione (allOf) consente di aggregare le proprietà dello schema da schemi diversi. Ad esempio, è possibile definire un tipo di dati Company riutilizzando tutte le proprietà dei tipi esistenti Contact e Error. ![Esempio di composizione.](https://help.qlik.com/it-IT/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* Il polimorfismo (oneOf/anyOf) consente di creare un'entità in grado di utilizzare le proprietà di diversi tipi di dati.
  * oneOf consente di definire un tipo di dati contenente le proprietà di uno dei tipi selezionati. Ad esempio, se si crea un'operazione per ottenere informazioni su un account di servizio, è possibile definire la risposta utilizzando la combinazione oneOf per ottenere tutte le proprietà di Error o tutte le proprietà di ServiceAccountCount. ![Esempio di polimorfismo.](https://help.qlik.com/it-IT/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/oneof.png)

  * anyOf consente di definire un tipo di dati contenente le proprietà di uno o diversi dei tipi selezionati. Ad esempio, è possibile definire un tipo di dati nervousSystem e un tipo skeleton contenenti proprietà diverse e utilizzare la combinazione anyOf per creare un tipo di dati contenente qualsiasi proprietà di uno di questi tipi.

    Una combinazione anyOf è valida purché contenga tutti i parametri richiesti di almeno uno dei tipi di dati selezionati. L'esempio seguente utilizza la proprietà brain\_weight del tipo nervousSystem e le proprietà skull\_height e teeth di skeleton.

    ![Esempio di combinazione che utilizza i tipi di dati nervousSystem e skeleton.](https://help.qlik.com/it-IT/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/anyof.png)

Per ulteriori informazioni sulla composizione e sul polimorfismo, vedere [Ereditarietà e polimorfismo](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) e [Differenza tra anyOf e oneOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof).

## Risposte

OAS 3.0 consente di definire nuovi tipi di risposta per le tue operazioni:

* Intervalli di risposta: invece di definire una risposta come 200, è possibile impostarla come 2XX, in modo da includere le risposte da 200 a 299.
* Risposte predefinite: è possibile definire una risposta predefinita da restituire quando non è definita una risposta specifica o per intervallo.

Le risposte definite con un codice esplicito hanno la precedenza sugli intervalli di risposta e sulle risposte predefinite, e gli intervalli di risposta hanno la precedenza sulle risposte predefinite. Nell'esempio seguente:

* La risposta 204 è definita e ha la precedenza sulle altre.
* La risposta 2XX si applica ai codici di risposta da 200 a 203 e da 205 a 299.
* La risposta predefinita si applica a tutte le risposte 1XX, 3XX, 4XX e 5XX.

![Sezione Risposte.](https://help.qlik.com/it-IT/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/responses-headers-api.png)

## Sicurezza

OAS 3.0 introduce nuovi schemi di sicurezza per la tua API:

* Autenticazione Bearer
* OpenIdConnect

## Limitazioni

OAS 3.0 consente di indicare che alcune proprietà sono di sola lettura o di sola scrittura.

Questa opzione è disponibile solo nei tipi di dati e non può essere definita in richieste o risposte a livello di operazione.

![Esempio di restrizione.](https://help.qlik.com/it-IT/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)