Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Rappresentazione della documentazione dell'API in API Gateway
<a name="api-gateway-documenting-api-content-representation"></a>

La documentazione dell'API in API Gateway è costituita da singole parti associate a specifiche entità API che includono API, risorsa, metodo, richiesta, risposta parametri del messaggio (ad esempio, percorso, query, intestazione), nonché autorizzazioni e modelli. 

In API Gateway, una parte della documentazione è rappresentata da una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa. L'intera documentazione dell'API è rappresentata dalla [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)raccolta. 

La documentazione di un'API implica la creazione di istanze di `DocumentationPart`, aggiungendole alla raccolta `DocumentationParts` e mantenendo le versioni delle parti della documentazione man mano che l'API evolve.

**Topics**
+ [Parti della documentazione](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [Versioni della documentazione](#api-gateway-documenting-api-content-representation-documentation-versions)

## Parti della documentazione
<a name="api-gateway-documenting-api-content-representation-documentation-parts"></a>

Una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa è un oggetto JSON che memorizza il contenuto della documentazione applicabile a una singola entità API. Sono inclusi contenuti UTF-8 e tutte le principali lingue di localizzazione per la documentazione. Il campo `properties` contiene il contenuto della documentazione sotto forma di mappa di coppie chiave-valore. La proprietà `location` identifica l'entità API associata. 

La forma della mappa di contenuti è determinata da te, lo sviluppatore dell'API. Il valore di una coppia chiave-valore può essere una stringa, un numero, un booleano, un oggetto o una matrice. La forma dell'oggetto `location` dipende dal tipo di entità di destinazione. 

La risorsa `DocumentationPart` supporta l'ereditarietà del contenuto: il contenuto della documentazione di un'entità API è applicabile agli elementi figlio dell'entità API. Per ulteriori informazioni sulla definizione di entità figlio ed ereditarietà del contenuto, consulta [Ereditare il contenuto da un'entità API di più specifiche generali](#api-gateway-documenting-api-content-inheritance). 

### Posizione di una parte della documentazione
<a name="api-gateway-documenting-api-content-representation-documentation-parts-target"></a>

La proprietà [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) di un'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza identifica un'entità API a cui si applica il contenuto associato. L'entità API può essere una risorsa API REST di API Gateway, ad esempio [Resource [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) o [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). L'entità può anche essere un parametro di messaggio, ad esempio un parametro di percorso URL, un parametro di stringa di query, un parametro di intestazione di richiesta o risposta, un corpo di richiesta o risposta o un codice di stato di risposta. 

Per specificare un'entità API, impostare l'attributo [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) dell'oggetto `location` su uno dei seguenti valori `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` o `RESPONSE_BODY`. 

A seconda dell'attributo `type` di un'entità API, è possibile specificare altri attributi `location`, tra cui [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) e [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Non tutti questi attributi sono validi per una determinata entità API. Ad esempio, `type`, `path`, `name` e `statusCode` sono attributi validi dell'entità `RESPONSE`, solo `type` e `path` sono attributi di posizione validi dell'entità `RESOURCE`. Non è corretto includere un campo non valido nell'attributo `location` di `DocumentationPart` per una determinata entità API.

Non tutti i campi `location` validi sono obbligatori. Ad esempio, `type` è il campo `location` valido e obbligatorio di tutte le entità API. Tuttavia, `method`, `path` e `statusCode` sono attributi validi ma non obbligatori per l'entità `RESPONSE`. Se non è specificato esplicitamente, un campo `location` valido assume il valore predefinito. Il valore predefinito di `path` è `/`, vale a dire la risorsa radice di un'API. Il valore predefinito di `method` o `statusCode` è `*`, ossia qualsiasi valore di metodo o codice di stato, rispettivamente.

### Contenuto di una parte della documentazione
<a name="api-gateway-documenting-api-content-representation-documentation-parts-content"></a>

Il valore di `properties` è codificato come stringa JSON. Il valore `properties` contiene tutte le informazioni che hai scelto per soddisfare i tuoi requisiti di documentazione. Ad esempio, la seguente è una mappa di contenuti valida: 

```
{
  "info": {
    "description": "My first API with Amazon API Gateway."
  },
  "x-custom-info" : "My custom info, recognized by OpenAPI.",
  "my-info" : "My custom info not recognized by OpenAPI."
}
```

Anche se API Gateway accetta qualsiasi stringa JSON valida come mappa di contenuti, gli attributi del contenuto sono trattati come due categorie: quelli che possono e quelli che non possono essere riconosciuti da OpenAPI. Nell'esempio precedente, `info`, `description` e `x-custom-info` sono riconosciuti da OpenAPI come oggetto, proprietà o estensione OpenAPI standard. Di contro, `my-info` non è conforme alle specifiche OpenAPI. API Gateway propaga gli attributi di contenuto conformi a OpenAPI nelle definizioni di entità API delle istanze di `DocumentationPart` associate. API Gateway non propaga gli attributi di contenuto non conformi nelle definizioni di entità API. 

Per un altro esempio, ecco un `DocumentationPart` mirato per un'entità `Resource`:

```
{
    "location" : {
        "type" : "RESOURCE",
        "path": "/pets"
    },
    "properties" : {
        "summary" : "The /pets resource represents a collection of pets in PetStore.",
        "description": "... a child resource under the root...",
    }
}
```

Qui, `type` e `path` sono entrambi campi validi per l'identificazione della destinazione del tipo `RESOURCE`. Per la risorsa radice (`/`), puoi omettere il campo `path`.

```
{
    "location" : {
        "type" : "RESOURCE"
    },
    "properties" : {
        "description" : "The root resource with the default path specification."
    }
}
```

È equivalente alla seguente istanza di `DocumentationPart`:

```
{
    "location" : {
        "type" : "RESOURCE",
        "path": "/"
    },
    "properties" : {
        "description" : "The root resource with an explicit path specification"
    }
}
```



### Ereditare il contenuto da un'entità API di specifiche più generali
<a name="api-gateway-documenting-api-content-inheritance"></a>

Il valore predefinito di un campo `location` facoltativo fornisce una descrizione di modello di un'entità API. Usando il valore predefinito dell'oggetto `location`, puoi aggiungere una descrizione generale nella mappa di `properties` a un'istanza di `DocumentationPart` con questo tipo di modello `location`. API Gateway estrae gli attributi della documentazione OpenAPI applicabili da `DocumentationPart` dell'entità API generica e li inserisce in un'entità API specifica con i campi `location` corrispondenti al modello `location` generale o corrispondenti al valore esatto, a meno che l'entità specifica non disponga già di un'istanza `DocumentationPart` associata. Questo comportamento è anche noto come ereditarietà del contenuto da un'entità API con specifiche più generali. 

L'ereditarietà del contenuto non si applica a determinati tipi di entità API. Per informazioni dettagliate, consulta la tabella seguente.

Quando un'entità API corrisponde a più di un modello di posizione di `DocumentationPart`, l'entità erediterà la parte della documentazione con i campi di posizione con la precedenza e le specificità più elevate. L'ordine di precedenza è `path` > `statusCode`. Per la corrispondenza con il campo `path`, API Gateway sceglie l'entità con il valore del percorso più specifico. La seguente tabella mostra questo comportamento con alcuni esempi.


| Caso | `path` | `statusCode` | `name` | Remarks | 
| --- | --- | --- | --- | --- | 
| 1 | /pets | \$1 | id |  La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione.  | 
| 2 | /pets | 200 | id |  La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione in caso di corrispondenza con il caso 1 e il caso 2, in quanto il caso 2 è più specifico del caso 1.   | 
| 3 | /pets/petId | \$1 | id |  La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione quando i casi 1, 2 e 3 sono corrispondenti, poiché il caso 3 ha una precedenza maggiore rispetto al caso 2 ed è più specifico del caso 1.  | 

Ecco un altro esempio per contrapporre un'istanza di `DocumentationPart` più generica con una più specifica. Il seguente messaggio di errore generale `"Invalid request error"` è inserito nelle definizioni di OpenAPI delle risposte dell'errore `400`, se non sostituite. 

```
{
    "location" : {
        "type" : "RESPONSE",
        "statusCode": "400"
    },
    "properties" : {
        "description" : "Invalid request error."
    }"
}
```

Con la seguente sostituzione, l'errore `400` che risponde ai metodi della risorsa `/pets` ha la descrizione `"Invalid petId specified"`. 

```
{
    "location" : {
        "type" : "RESPONSE",
        "path": "/pets",
        "statusCode": "400"
    },
    "properties" : "{
        "description" : "Invalid petId specified."
    }"
}
```

### Campi di posizione di valid `DocumentationPart`
<a name="api-gateway-documenting-api-content-representation-target-specification"></a>

La tabella seguente mostra i campi validi e obbligatori, nonché i valori predefiniti applicabili di una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa associata a un determinato tipo di entità API.


| Entità API | Campi di posizione validi | Campi di posizione obbligatori | Valori dei campi predefiniti | Contenuto ereditabile | 
| --- | --- | --- | --- | --- | 
| [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) |  <pre>{<br />    "location": {<br />        "type": "API" <br />    }, <br />    ... <br />}</pre>  | type | N/A | No | 
| [Risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) |  <pre>{ <br />    "location": { <br />        "type": "RESOURCE", <br />        "path": "resource_path" <br />    }, <br />    ... <br />}</pre>  | type | Il valore predefinito di path è /.  | No | 
| [Metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) |  <pre>{ <br />    "location": { <br />        "type": "METHOD", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | I valori predefiniti di path e method sono / e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per qualsiasi valore.  | 
| Parametro di query |  <pre>{ <br />    "location": { <br />        "type": "QUERY_PARAMETER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "query_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type | I valori predefiniti di path e method sono / e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. | 
| Corpo di richiesta |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | I valori predefiniti di path e method sono / e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. | 
| Parametro di intestazione di richiesta |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_HEADER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | I valori predefiniti di path e method sono / e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. | 
| Parametro di percorso richiesta |  <pre>{ <br />    "location": { <br />        "type": "PATH_PARAMETER", <br />        "path": "resource/{path_parameter_name}", <br />        "method": "HTTP_verb",<br />        "name": "path_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type, name | I valori predefiniti di path e method sono / e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. | 
| Risposta |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. | 
| Intestazione della risposta |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_HEADER", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code", <br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. | 
| Corpo di risposta |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente.  | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. | 
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) |  <pre>{ <br />    "location": { <br />        "type": "AUTHORIZER", <br />        "name": "authorizer_name" <br />    }, <br />    ... <br />}</pre>  | type | N/A | No | 
| [Modello](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) |  <pre>{ <br />    "location": { <br />        "type": "MODEL", <br />        "name": "model_name" <br />    }, <br />    ... <br />}</pre>  | type | N/A | No | 

## Versioni della documentazione
<a name="api-gateway-documenting-api-content-representation-documentation-versions"></a>

Una versione della documentazione è un'istantanea della [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)raccolta di un'API ed è contrassegnata con un identificatore di versione. La pubblicazione della documentazione di un'API implica la creazione di una versione della documentazione, l'associazione con una fase API e l'esportazione della versione specifica della fase della documentazione dell'API in un file OpenAPI esterno. In API Gateway, un'istantanea della documentazione è rappresentata come una [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa. 

Quando aggiorni un'API, crei nuove versioni dell'API. In API Gateway, gestisci tutte le versioni della documentazione utilizzando la [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta.