Publicación de documentación de la API mediante la API de REST de API Gateway

Para publicar la documentación de una API, cree, actualice u obtenga una snapshot de documentación y después asóciela a una etapa de API. Cuando crea una snapshot de documentación, también puede asociarla a una etapa de API al mismo tiempo.

Crear una snapshot de documentación y asociarla a una etapa de API

Para crear una snapshot de piezas de documentación de una API y asociarla a una etapa de API al mismo tiempo, envíe la siguiente solicitud 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"
}

Si es correcta, la operación devuelve una respuesta 200 OK que contiene la instancia DocumentationVersion recién creada como la carga.

También puede crear una instantánea de documentación sin asociarla primero a una etapa de API y después llamar a restapi:update para asociar la instantánea a una etapa de API específica. También puede actualizar o consultar una snapshot de documentación existente y después actualizar su asociación de etapa. Le mostramos los pasos en las próximas cuatro secciones.

Crear una snapshot de documentación

Para crear una instantánea de piezas de documentación de una API, cree un nuevo recurso DocumentationVersion y agréguelo a la colección DocumentationVersions de la 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"
}

Si es correcta, la operación devuelve una respuesta 200 OK que contiene la instancia DocumentationVersion recién creada como la carga.

Actualizar una snapshot de documentación

Solo puede actualizar una instantánea de documentación modificando la propiedad description del recurso DocumentationVersion correspondiente. El siguiente ejemplo muestra cómo actualizar la descripción de la snapshot de documentación identificada por su identificador de versión, version (p. ej., 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."
    }]
}

Si es correcta, la operación devuelve una respuesta 200 OK que contiene la instancia DocumentationVersion actualizada como la carga.

Obtener una snapshot de documentación

Para obtener una instantánea de documentación, envíe una solicitud GET al recurso DocumentationVersion especificado. El siguiente ejemplo muestra cómo obtener una snapshot de documentación de un identificador de versión determinado, 1.0.0.

GET /restapis/<restapi_id>/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

Asociar una snapshot de documentación con una etapa de API

Para publicar la documentación de la API, asocie una snapshot de documentación a una etapa de API. Debe haber creado una etapa de API antes de asociar la versión de documentación a la etapa.

Para asociar una instantánea de documentación a una etapa de API, mediante la API de REST de API Gateway, llame a la operación stage:update para establecer la versión de documentación que desee en la propiedad 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"
    }]
}

Descargar una snapshot de documentación asociada a una etapa

Una vez asociada una versión de las partes de la documentación a una etapa, puede exportar las partes de la documentación junto con las definiciones de la entidad de la API a un archivo externo mediante la consola de API Gateway, la API REST de API Gateway, uno de sus SDK o la AWS CLI para API Gateway. El proceso es el mismo que para exportar la API. El formato del archivo exportado puede ser JSON o YAML.

Mediante la API de REST de API Gateway, también puede establecer explícitamente el parámetro de consulta extension=documentation,integrations,authorizers para incluir las piezas de documentación de la API, las integraciones de la API y los autorizadores en una exportación de la API. De forma predeterminada, se incluyen las piezas de documentación, pero se excluyen las integraciones y los autorizadores cuando se exporta una API. La salida predeterminada de la exportación de API es adecuada para la distribución de la documentación.

Para exportar la documentación de la API en un archivo JSON de OpenAPI externo mediante la API de REST de API Gateway, envíe la siguiente solicitud 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

Aquí, el objeto x-amazon-apigateway-documentation contiene las piezas de documentación y las definiciones de la entidad de API contienen las propiedades de documentación admitidas por OpenAPI. La salida no incluye los detalles de la integración ni de los autorizadores de Lambda (que anteriormente se denominaban autorizadores personalizados). Para incluir ambos detalles, establezca extensions=integrations,authorizers,documentation. Para incluir los detalles de las integraciones pero no de los autorizadores, establezca extensions=integrations,documentation.

Debe definir el encabezado Accept:application/json en la solicitud para mostrar el resultado en un archivo JSON. Para producir la salida en formato YAML, cambie el encabezado de la solicitud a Accept:application/yaml.

A modo de ejemplo, vamos a examinar una API que expone un método GET sencillo en el recurso raíz (/). Esta API tiene cuatro entidades de API definidas en un archivo de definición de OpenAPI, una para cada uno de los tipos API, MODEL, METHOD y RESPONSE. Se ha añadido una pieza de documentación a cada una de las entidades API, METHOD y RESPONSE. Al llamar al comando de exportación de la documentación anterior, obtenemos el siguiente resultado, con las piezas de documentación mostradas dentro del objeto x-amazon-apigateway-documentation como una extensión a un archivo de OpenAPI estándar.

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

Para un atributo compatible con OpenAPI definido en el mapa properties de una pieza de documentación, API Gateway inserta el atributo en la definición de la entidad de API asociada. Un atributo de x-something es una extensión de OpenAPI estándar. Esta extensión se propaga a la definición de la entidad de API. Véase, por ejemplo, el atributo x-example del método GET. Un atributo como foo no forma parte de la especificación de OpenAPI y no se incluye en sus definiciones de entidad de API asociadas.

Si una herramienta de representación de la documentación (por ejemplo, la interfaz de usuario de OpenAPI) analiza las definiciones de la entidad de API para extraer los atributos de documentación, ninguno de los atributos properties que no sean compatibles con OpenAPI de una instancia de DocumentationPart estará disponible para la herramienta. Sin embargo, si una herramienta de representación de documentación analiza el objeto x-amazon-apigateway-documentation para obtener contenido, o si la herramienta llama a restapi:documentation-parts y documenationpart:by-id para recuperar piezas de documentación de API Gateway, la herramienta podrá mostrar todos los atributos de la documentación.

Para exportar la documentación con definiciones de entidad de API que contengan detalles de la integración en un archivo JSON de OpenAPI, envíe la siguiente solicitud 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

Para exportar la documentación con definiciones de entidad de API que contengan detalles de las integraciones y autorizadores a un archivo YAML de OpenAPI, envíe la siguiente solicitud 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

Para utilizar la consola de API Gateway para exportar y descargar la documentación publicada de una API, siga las instrucciones de Exportar API REST con la consola de API Gateway.