Importa API la documentazione

Analogamente all'importazione delle definizioni di API entità, è possibile importare parti della documentazione da un API file Open esterno in un API Gateway API in. Le parti della to-be-imported documentazione all'interno dell'x-amazon-apigateway-documentation oggettoestensione vengono specificate in un file di API definizione aperto valido. L'importazione della documentazione non modifica le definizioni di API entità esistenti.

È possibile unire le parti di documentazione appena specificate in parti di documentazione esistenti in API Gateway o sovrascrivere le parti della documentazione esistenti. In questa MERGE modalità, una nuova parte della documentazione definita nel API file Open viene aggiunta alla DocumentationParts raccolta di. API Se un elemento DocumentationPart importato esiste già, un attributo importato sostituisce quello esistente se i due sono diversi. Altri attributi della documentazione esistenti rimangono inalterati. In questa OVERWRITE modalità, l'intera DocumentationParts raccolta viene sostituita in base al file di API definizione aperto importato.

Importazione di parti della documentazione utilizzando il API Gateway REST API

Per importare API la documentazione utilizzando il API Gateway RESTAPI, chiamate l'operazione documentationpart:import. L'esempio seguente mostra come sovrascrivere le parti della documentazione esistenti di un API con un unico GET / metodo, restituendo una risposta in caso di successo. 200 OK

OpenAPI 3.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
   "openapi": "3.0.0",
   "info": {
      "description": "description",
      "version": "1",
      "title": "doc"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "x-amazon-apigateway-documentation": {
      "version": "1.0.3",
      "documentationParts": [
         {
            "location": {
               "type": "API"
            },
            "properties": {
               "description": "API description",
               "info": {
                  "description": "API info description 4",
                  "version": "API info version 3"
               }
            }
         },
         {
            "location": {
               "type": "METHOD",
               "method": "GET"
            },
            "properties": {
               "description": "Method description."
            }
         },
         {
            "location": {
               "type": "MODEL",
               "name": "Empty"
            },
            "properties": {
               "title": "Empty Schema"
            }
         },
         {
            "location": {
               "type": "RESPONSE",
               "method": "GET",
               "statusCode": "200"
            },
            "properties": {
               "description": "200 response"
            }
         }
      ]
   },
   "servers": [
      {
         "url": "/"
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}

OpenAPI 2.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
  "swagger": "2.0",
  "info": {
    "description": "description",
    "version": "1",
    "title": "doc"
  },
  "host": "",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "paths": {
    "/": {
      "get": {
        "description": "Method description.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation": {
    "version": "1.0.3",
    "documentationParts": [
      {
        "location": {
          "type": "API"
        },
        "properties": {
          "description": "API description",
          "info": {
            "description": "API info description 4",
            "version": "API info version 3"
          }
        }
      },
      {
        "location": {
          "type": "METHOD",
          "method": "GET"
        },
        "properties": {
          "description": "Method description."
        }
      },
      {
        "location": {
          "type": "MODEL",
          "name": "Empty"
        },
        "properties": {
          "title": "Empty Schema"
        }
      },
      {
        "location": {
          "type": "RESPONSE",
          "method": "GET",
          "statusCode": "200"
        },
        "properties": {
          "description": "200 response"
        }
      }
    ]
  }
}

In caso di esito positivo, questa richiesta restituisce una risposta 200 OK contenente l'elemento DocumentationPartId importato nel payload.

{
  "ids": [
    "kg3mth",
    "796rtf",
    "zhek4p",
    "5ukm9s"
  ]
}

Inoltre, potete anche chiamare restapi:import o restapi:put, fornendo le parti della documentazione nell'x-amazon-apigateway-documentationoggetto come parte del file Open di input della definizione. API API Per escludere le parti della documentazione dall'APIimportazione, impostate i parametri della query di richiesta. ignore=documentation

Importazione di parti della documentazione utilizzando la console API Gateway

Le seguenti istruzioni descrivono come importare le parti della documentazione.

Per utilizzare la console per importare parti di documentazione API da un file esterno

1. Nel riquadro di navigazione principale scegli Documentazione.

2. Seleziona Importa.

3. Se è disponibile la documentazione esistente, seleziona Sovrascrivi o Unisci per la nuova documentazione.

4. Seleziona Scegli il file per caricare un file da un'unità oppure immettere il contenuto di un file nella vista del file. Per un esempio, consulta il payload della richiesta di esempio in Importazione di parti della documentazione utilizzando il API Gateway REST API.

5. Scegli in che modo gestire gli avvisi durante l'importazione. Seleziona Avvisi di errore o Ignora avvisi. Per ulteriori informazioni, consulta Errori e avvisi derivanti dall'importazione in Gateway API API.

6. Seleziona Importa.