Modifica delle definizioni degli schemi

Modifica online

Gli schemi forniscono agli sviluppatori informazioni sulla richiesta che devono inviare o sulla risposta che dovrebbero aspettarsi di ricevere quando richiamano un'operazione API. È possibile modificare gli schemi che sono stati precedentemente creati in vari punti nella propria definizione API.

Prima di iniziare

Nota: gli schemi vengono compilati prima di essere utilizzati per la convalida. Poiché il processo di compilazione è più lungo del processo di convalida, le risorse utente dello schema compilato vengono memorizzate in una cache. La capacità limitata della cache può causare l'eliminazione delle voci più vecchie dalla cache quando vengono aggiunte voci più nuove. Gli schemi le cui risorse sono state rimosse dalla cache devono essere ricompilati, il che può causare ritardi significativi nella convalida.

Per i dettagli delle aree nella tua definizione API da cui puoi modificare uno schema, consulta i seguenti argomenti:

Informazioni su questa attività

Nota: questa attività fa riferimento alla configurazione di una definizione API OpenAPI 2.0 . Per i dettagli su come configurare una definizione API OpenAPI 3.0 , vedi Modifica di una definizione API OpenAPI 3.0.

Puoi completare questa attività utilizzando l'applicazione IU API Designer o utilizzando l'IU API Manager basata sul browser.

La vista tabellare mostra le proprietà di uno schema insieme ai loro attributi essenziali, quali nome, tipo, descrizione e stato di obbligatorietà. Il menu a comparsa secondario consente di visualizzare e modificare gli attributi più dettagliati e meno utilizzati associati a ciascun campo dati.

In qualsiasi momento puoi passare direttamente al codice sorgente YAML OpenAPI sottostante cliccando Fonte sull'icona Icona origine OpenAPI . Per tornare al modulo di progettazione, clicca sull'icona Icona modulo Modulo.

Procedura

È possibile configurare le seguenti impostazioni relative alla definizione dello schema:

Nome schema: questo nome definisce una chiave che consente di fare riferimento a questo schema da un'altra parte nella definizione API; il riferimento ha il formato seguente:
```
#/definitions/Name
```
Per modificare il nome, clicca sull'icona Origine, modifica il valore nel campo, quindi clicca su Salva.
Facoltativo: Titolo : Il titolo dello schema.
Tipo: il tipo di dati dello schema; selezionare uno dei seguenti:
- - array
  - booleano
  - intero
  - numero
  - oggetto
  - stringa
Nota: se si modifica il tipo di uno schema esistente, tutte le impostazioni esistenti non rilevanti per il nuovo tipo vengono ancora conservate nell'origine OpenAPI anche se non sono più visualizzate nell'interfaccia utente. Si consiglia quindi di evitare di trasferire uno schema da un tipo all'altro, ma piuttosto di creare un nuovo schema o di modificare direttamente il codice sorgente dell' OpenAPI; per aprire l'editor del codice sorgente, fare clic sull'icona "Source " .
Proprietà : la proprietà dello schema. Per aggiungere una proprietà allo schema, clicca su "Aggiungi" accanto all'intestazione della sezione "Proprietà", inserisci i dettagli e clicca su "Salva".
Ulteriori impostazioni dello schema in base al tipo di proprietà selezionato. Per visualizzare e modificare queste impostazioni dello schema, clicca sul menu Opzioni accanto alla proprietà che desideri visualizzare e seleziona Dettagli.
- booleano: nessuna impostazione specifica del tipo.
- numero intero:
  - Formato: un modificatore del tipo di dati facoltativo. Per ulteriori informazioni, consultare la sezione "Tipi di dati" nella specifica " OpenAPI ".
  - Multiple Of (multiplo di): la divisione di un'istanza intera in base a questo valore deve risultare in un numero intero.
  - Massimo: un'istanza intera deve essere inferiore o uguale a questo valore.
  - Massimo esclusivo: un'istanza intera deve essere strettamente inferiore a questo valore.
  - Minimo: un'istanza intera deve essere maggiore o uguale a questo valore.
  - Minimo esclusivo: un'istanza intera deve essere strettamente maggiore di questo valore.
- numero:
  - Formato: un modificatore del tipo di dati facoltativo. Per ulteriori informazioni, consultare la sezione "Tipi di dati" nella specifica " OpenAPI ".
  - Multiplo di: la divisione di un'istanza numerica in base a questo valore deve risultare in un numero intero.
  - Massimo: un'istanza di numero deve essere minore o uguale a questo valore.
  - Massimo esclusivo: un'istanza di numero deve essere rigorosamente inferiore a questo valore.
  - Minimo: un'istanza di numero deve essere maggiore o uguale a questo valore.
  - Minimo esclusivo: un'istanza di numero deve essere strettamente maggiore di questo valore.
- oggetto :
  - Numero massimo di proprietà: il numero di proprietà in un'istanza dell'oggetto deve essere minore o uguale a questo valore.
  - Proprietà minime: il numero di proprietà in un'istanza dell'oggetto deve essere maggiore o uguale a questo valore.
  - Proprietà richieste: un array di nomi proprietà; ogni nome di proprietà nell'array deve corrispondere al nome di una proprietà in un'istanza dell'oggetto. Per aggiungere un nome proprietà richiesto, fare clic su Aggiungi accanto all'intestazione della sezione Proprietà richieste , immettere il nome, quindi fare clic su Crea.
- stringa:
  - Formato: un modificatore del tipo di dati facoltativo. Per ulteriori informazioni, consultare la sezione "Tipi di dati" nella specifica " OpenAPI ".
  - Pattern: un'espressione regolare; un'istanza stringa deve corrispondere correttamente all'espressione.
  - Lunghezza massima: il numero massimo consentito di caratteri in un'istanza stringa.
  - Lunghezza minima: il numero minimo consentito di caratteri in un'istanza di stringa.
  - Enum: un array di valori stringa; un'istanza stringa deve corrispondere a uno dei valori array. Per aggiungere un valore di enumerazione, fare clic su Aggiungi, immettere il valore e fare clic su Crea.
Impostazioni generali; selezionare le opzioni richieste:
- Obbligatorio : è necessario specificare una proprietà associata a questo schema.
- Sola lettura: una proprietà associata a questo schema può essere restituita in una risposta ma non deve essere inclusa in una richiesta. Ad esempio, le proprietà i cui valori sono identificativi generati dal sistema verranno definiti come Sola lettura perché i client delle applicazioni non sarebbero in grado di impostarli.
Valore di esempio: un valore di esempio. Qualunque cosa inserisci qui verrà visualizzata così com'è nel Catalogo dei consumatori del Portale degli sviluppatori.
Documentazione esterna: una risorsa esterna per la documentazione estesa; fornire le seguenti informazioni:
- URL (obbligatorio): L' URL e della documentazione di destinazione.
- Descrizione: una descrizione facoltativa della documentazione di destinazione. È possibile utilizzare la sintassi CommonMark per la rappresentazione in formato RTF.
Xml: Metadati che consentono definizioni di modelli XML più dettagliate; fornire le seguenti informazioni:
- Nome : sostituisce il nome dell'elemento o dell'attributo utilizzato per la proprietà dello schema descritta.
- Spazio dei nomi : l' URL e della definizione dello spazio dei nomi.
- Prefisso:: il prefisso da utilizzare per il Nome.
- Attributo: specifica se la definizione della proprietà viene tradotta in un attributo invece che in un elemento.
- Con wrap: per una definizione di array, specifica se l'array è con wrap (ad esempio, <books><book/><book/></books>) o unwrapped (<book/><book/>).
Fare clic su Salva una volta terminato.

Esempio

Definendo le proprietà, è possibile creare strutture dati più complesse. Ad esempio, è possibile definire uno schema Indirizzo con le proprietà riportate di seguito:

Tabella 1. NOME DELL'IMMOBILE e TIPO DI IMMOBILE
NOME PROPRIETÀ	TIPO DI PROPRIETÀ
`street1`	`string`
`street2`	`string`
`city`	`string`
`state`	`string`
`zip_code`	`string`

e definire quindi lo schema BankBranch che ha le seguenti proprietà, una delle quali è un riferimento allo schema Address:

Tabella 2. NOME DELL'IMMOBILE e TIPO DI IMMOBILE
NOME PROPRIETÀ	TIPO DI PROPRIETÀ
`address`	`address`
`type`	`string`
`id`	`string`

Cosa fare successivamente

Se necessario, utilizzare la traccia breadcrumb per passare a un'altra posizione nella gerarchia dell'oggetto su cui si sta lavorando.