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à.
# Pubblicare la documentazione dell'API utilizzando l'API REST di API Gateway
Per pubblicare la documentazione per un'API, crea, aggiorna o ottieni uno snapshot della documentazione, quindi associa lo snapshot della documentazione a una fase dell'API. Quando crei uno snapshot della documentazione, puoi anche contemporaneamente associarlo a una fase dell'API.
**Topics**
+ [Creare uno snapshot della documentazione e associarlo a una fase dell'API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Creare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Aggiornare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Ottenere uno snapshot della documentazione](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Associare uno snapshot della documentazione a una fase dell'API](#api-gateway-documenting-api-publishing-stage-association)
+ [Scaricare uno snapshot della documentazione associato a una fase](#api-gateway-documenting-api-publishing-export-documentation-version)
## Creare uno snapshot della documentazione e associarlo a una fase dell'API
Per creare uno snapshot delle parti della documentazione di un'API e associarlo contemporaneamente a una fase dell'API, invia la seguente richiesta `POST`:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload.
In alternativa, è possibile creare uno snapshot della documentazione senza associarlo prima a una fase dell'API e quindi chiamare [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) per associare lo snapshot a una fase dell'API specificata. Puoi inoltre aggiornare o interrogare uno snapshot della documentazione esistente e quindi aggiornare la relativa associazione della fase. Le fasi vengono illustrate nelle prossime quattro sezioni.
## Creare uno snapshot della documentazione
Per creare un'istantanea delle parti della documentazione di un'API, crea una nuova [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa e aggiungila alla [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta dell'API:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload.
## Aggiornare uno snapshot della documentazione
È possibile aggiornare un'istantanea della documentazione solo modificando la `description` proprietà della risorsa corrispondente. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come aggiornare la descrizione dello snapshot della documentazione come identificata dal relativo identificatore di versione, `version`, ad esempio `1.0.0`.
```
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/description",
"value": "My API for testing purposes."
}]
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente l'istanza `DocumentationVersion` aggiornata come payload.
## Ottenere uno snapshot della documentazione
Per ottenere un'istantanea della documentazione, invia una `GET` richiesta relativa alla risorsa specificata. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come ottenere uno snapshot della documentazione di un dato identificatore di versione, 1.0.0.
```
GET /restapis//documentation/versions/1.0.0 HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
## Associare uno snapshot della documentazione a una fase dell'API
Per pubblicare la documentazione dell'API, associa uno snapshot della documentazione a una fase dell'API. Devi aver già creato la fase dell'API prima di associare la versione della documentazione alla fase.
Per associare uno snapshot della documentazione a una fase dell'API utilizzando l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), esegui l'operazione [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) per impostare a versione della documentazione desiderata sulla proprietà `stage.documentationVersion`:
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## Scaricare uno snapshot della documentazione associato a una fase
Dopo aver associato una versione delle parti della documentazione a uno stage, è possibile esportare le parti della documentazione insieme alle definizioni delle entità API, in un file esterno, utilizzando la console API Gateway, l'API REST API Gateway, una delle sue SDKs, o il AWS CLI for API Gateway. Il processo è uguale a quello utilizzato per esportare l'API. Il formato del file esportato può essere JSON o YAML.
Utilizzando l'API REST di API Gateway, puoi anche impostare esplicitamente il parametro di query `extension=documentation,integrations,authorizers` per includere le parti della documentazione dell'API, le integrazioni API e le autorizzazioni in un'esportazione API. Per impostazione predefinita, le parti della documentazione sono incluse, ma le integrazioni e le autorizzazioni sono escluse quando si esporta un'API. L'output predefinito di un'esportazione API è adatto per la distribuzione della documentazione.
Per esportare la documentazione dell'API in un file OpenAPI JSON esterno usando l'API REST di API Gateway, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Qui, l'oggetto `x-amazon-apigateway-documentation` contiene le parti della documentazione e la definizione dell'entità API contiene le proprietà della documentazione supportate da OpenAPI. L'output non include dettagli sull'integrazione o sulle autorizzazioni Lambda (note in precedenza come autorizzazioni ad hoc). Per includere entrambi i dettagli, imposta `extensions=integrations,authorizers,documentation`. Per includere i dettagli delle integrazioni ma non delle autorizzazioni, imposta `extensions=integrations,documentation`.
Imposta l'intestazione `Accept:application/json` nella richiesta per inserire l'output del risultato in un file JSON. Per produrre l'output YAML, imposta l'intestazione della richiesta su `Accept:application/yaml`.
Ad esempio, esamineremo un'API che espone un semplice metodo `GET` sulla risorsa radice (`/`). Questa API ha quattro entità API definite in un file di definizione OpenAPI, uno per ciascuno dei tipi `API`, `MODEL`, `METHOD` e `RESPONSE`. Una parte della documentazione è stata aggiunta a ciascuna delle entità `API`, `METHOD` e `RESPONSE`. Chiamando il precedente comando di esportazione della documentazione, otteniamo il seguente output, con le parti della documentazione elencate nell'oggetto `x-amazon-apigateway-documentation` come estensione di un file OpenAPI standard.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
Per un attributo conforme a OpenAPI definito nella mappa di `properties` di una parte della documentazione, API Gateway inserisce l'attributo nella definizione dell'entità API associata. Un attributo di `x-something` è un'estensione OpenAPI standard. Questa estensione viene propagata nella definizione dell'entità API. Ad esempio, consulta l'attributo `x-example` per il metodo `GET`. Un attributo come `foo` non fa parte delle specifiche OpenAPI e non viene inserito nelle definizioni delle entità API associate.
Se uno strumento di rendering della documentazione (ad esempio [OpenAPI UI](https://swagger.io/tools/swagger-ui/)) analizza le definizioni dell'entità API per estrarre gli attributi della documentazione, qualsiasi attributo `properties` non conforme a OpenAPI di un'istanza di `DocumentationPart` non è disponibile per lo strumento. Tuttavia, se uno strumento di rendering della documentazione analizza l'oggetto `x-amazon-apigateway-documentation` per ottenere i contenuti o se lo strumento chiama [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) e [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) per recuperare le parti della documentazione da API Gateway, tutti gli attributi della documentazione sono disponibili per la visualizzazione con lo strumento.
Per esportare la documentazione con definizioni di entità API contenenti i dettagli delle integrazioni in un file OpenAPI JSON, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Per esportare la documentazione con definizioni di entità API contenenti dettagli delle integrazioni e delle autorizzazioni in un file OpenAPI YAML, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Per usare la console API Gateway per esportare e scaricare la documentazione pubblicata di un'API, segui le istruzioni in [Esportazione di un'API REST tramite la console API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console).