Especifico mis API de AWS API Gateway a través de la especificación Open API. Las especificaciones contienen una gran cantidad de documentación que quiero que los desarrolladores de clientes utilicen al integrarse con las API. Sin embargo, parece que la documentación que agregamos a la especificación Open API no se exporta desde API Gateway y, por lo tanto, no está disponible para el consumo.

Como ya se mencionó, empiezo con una especificación Open API en JSON. Importo esto a API Gateway usando el recurso CloudFormation AWS::ApiGateway::RestApi.

Después de esto, implemento la API en una etapa y, finalmente, exporto la documentación de esta etapa API + usando el aws cli:

aws apigateway get-export \
    --parameters extensions='documentation' \
    --rest-api-id abc123 \
    --stage-name api \
    --export-type swagger \
    ./docs.json

Parece que a esta exportación le faltan muchas propiedades de documentación cruciales, como description y pattern.

Un ejemplo de parámetro Open API en mi API:

{
    in: 'path',
    name: 'service',
    type: 'string',
    required: true,
    pattern: '^[-a-zA-Z0-9]+$',
    description: 'Name of the Service (document) to retrieve.'
}

Cuando exporto esto con el comando aws-cli anterior, obtengo:

{
    "name" : "service",
    "in" : "path",
    "required" : true,
    "type" : "string"
}

Las propiedades description y pattern se han eliminado de la exportación de documentación, lo cual es malo, ya que realmente son la parte principal de la documentación para este parámetro.

También vale la pena mencionar que si exporto la misma API en la consola de AWS (extensiones Swagger + API Gateway) obtengo la misma definición de parámetro que obtuve de la exportación de documentación.

También vale la pena mencionar que todas las integraciones se basan en el proxy Lambda si eso marca la diferencia.

3
Carl 5 abr. 2017 a las 20:37

2 respuestas

La mejor respuesta

Una vez que se importa una plantilla Swagger, API Gateway divide la definición de API y su documentación en dos entidades separadas. Esto le permite modificar y desplegar los dos de forma independiente.

La función de exportación solo exporta lo que se implemente en una etapa. La importación de una plantilla Swagger hará que se importen tanto la definición de API como las partes de documentación. Sin embargo, parece que solo implementó la definición de API. Debe publicar explícitamente la documentación antes de que esté disponible en la exportación.

enter image description here

Como señaló, también puede usar la CLI para publicar una nueva versión de los documentos:

aws apigateway create-documentation-version \ --rest-api-id abc123 \ --documentation-version 1 \ --stage-name api

3
Stefano Buliani 5 abr. 2017 a las 18:44

Con un poco de ayuda del equipo de API Gateway, esto se ha resuelto.

Parece que faltaba un paso en mi flujo de trabajo. Después de implementar la API, se debe implementar la documentación:

aws apigateway create-documentation-version \
    --rest-api-id abc123 \
    --documentation-version 1 \
    --stage-name api

Después de hacer esto, el comando de exportación generará la documentación en lugar de la definición de API como parece que lo hizo anteriormente.

0
Carl 5 abr. 2017 a las 18:42