Importar la documentación de API - Amazon API Gateway
Importar piezas de documentación mediante la API de REST de API GatewayImportar piezas de documentación mediante la consola de API Gateway

Importar la documentación de API

De igual modo que para importar definiciones de entidad de API, puede importar piezas de documentación de un archivo de OpenAPI externo a una API mediante API Gateway. Las piezas de documentación que se van a importar se especifican en la extensión Objeto x-amazon-apigateway-documentation en un archivo de definición de OpenAPI válido. La importación de la documentación no modifica las definiciones de entidad de API existentes.

Tiene la opción de combinar las piezas de documentación recién especificadas en piezas de documentación existentes en API Gateway o de sobrescribir las piezas de documentación existentes. En el modo MERGE, una nueva pieza de documentación definida en el archivo de OpenAPI se añade a la colección DocumentationParts de la API. Si ya existe un elemento DocumentationPart importado, el atributo importado reemplaza al existente si los dos son diferentes. Todos los demás atributos de documentación existentes permanecen tal como están. En el modo OVERWRITE, toda la colección DocumentationParts se reemplaza de acuerdo con el archivo de definición de OpenAPI importado.

Importar piezas de documentación mediante la API de REST de API Gateway

Para importar la documentación de API mediante la API de REST de API Gateway, llame a la operación documentationpart:import. En el siguiente ejemplo, se muestra cómo sobrescribir las piezas de documentación existentes de una API con un único método GET / , que devuelve una respuesta 200 OK si se ejecuta correctamente.

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"
        }
      }
    ]
  }
}

Cuando se ejecuta correctamente, esta solicitud devuelve una respuesta 200 OK que contiene el elemento DocumentationPartId importado en la carga.

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

Además, también puede llamar a restapi:import o restapi:put, proporcionando las piezas de documentación en el objeto x-amazon-apigateway-documentation como parte del archivo de OpenAPI de entrada de la definición de la API. Para excluir piezas de documentación de la importación de API, establezca ignore=documentation en los parámetros de consulta de la solicitud.

Importar piezas de documentación mediante la consola de API Gateway

Las siguientes instrucciones describen cómo importar piezas de documentación.

Para utilizar la consola para importar piezas de documentación de una API desde un archivo externo

  1. En el panel de navegación principal, elija Documentación.

  2. Seleccione Importar.

  3. Si ya tiene documentación, seleccione Sobrescribir o Fusionar la nueva documentación.

  4. Elija Seleccionar archivo para cargar un archivo de una unidad, o ingrese el contenido del archivo en la vista de archivos. Para ver un ejemplo, consulte la carga de la solicitud de ejemplo de Importar piezas de documentación mediante la API de REST de API Gateway.

  5. Elija cómo gestionar las advertencias durante la importación. Seleccione Error en advertencias o Ignorar advertencias. Para obtener más información, consulte Errores y advertencias al importar la API a API Gateway.

  6. Seleccione Importar.