Publiez de API la documentation à l'aide de la API passerelle REST API

Pour publier la documentation d'uneAPI, créer, mettre à jour ou obtenir un instantané de documentation, puis associer l'instantané de documentation à une API étape. Lorsque vous créez un instantané de documentation, vous pouvez également l'associer à une API étape en même temps.

Créez un instantané de documentation et associez-le à une API étape

Pour créer un instantané des parties API de la documentation d'un utilisateur et l'associer à une API étape en même temps, soumettez la POST demande suivante :

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 l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion nouvellement créée en tant que charge utile.

Vous pouvez également créer un instantané de documentation sans l'associer d'abord à une API étape, puis appeler restapi:update pour associer l'instantané à une étape spécifiée. API Vous pouvez également mettre à jour ou interroger un instantané de documentation existant, puis mettre à jour son association à une étape donnée. Nous présentons les étapes correspondantes au cours des quatre sections suivantes.

Création d'un instantané de documentation

Pour créer un instantané des parties API de la documentation d'un utilisateur, créez une nouvelle DocumentationVersionressource et ajoutez-la à la DocumentationVersionscollection des 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 l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion nouvellement créée en tant que charge utile.

Mise à jour d'un instantané de documentation

Vous ne pouvez mettre à jour un instantané de documentation qu'en modifiant la description propriété de la DocumentationVersionressource correspondante. L'exemple suivant montre comment mettre à jour la description de l'instantané de la documentation tel qu'identifié par son identifiant de version, version, par exemple, 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 l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion mise à jour en tant que charge utile.

Obtention d'un instantané de documentation

Pour obtenir un instantané de la documentation, soumettez une GET demande pour la DocumentationVersionressource spécifiée. L'exemple suivant montre comment obtenir un instantané de documentation d'un identifiant de version donné, 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

Associer un instantané de documentation à une API étape

Pour publier la API documentation, associez un instantané de documentation à une API étape. Vous devez avoir déjà créé une API étape avant d'associer la version de documentation à l'étape.

Pour associer un instantané de documentation à une API étape à l'aide de la APIpasserelle REST API, appelez l'opération stage:update pour définir la version de documentation souhaitée sur la propriété : 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"
    }]
}

Téléchargement d'un instantané de documentation associé à une étape

Une fois qu'une version des parties de la documentation est associée à une étape, vous pouvez exporter les parties de la documentation avec les définitions des API entités vers un fichier externe, à l'aide de la console API Gateway, de la API passerelle RESTAPI, de l'une de ses SDKs versions ou de la API passerelle AWS CLI for Gateway. Le processus est le même que pour l'exportation duAPI. Le format de fichier exporté peut être JSON ouYAML.

À l'aide de la API passerelle RESTAPI, vous pouvez également définir explicitement le paramètre de extension=documentation,integrations,authorizers requête pour inclure les parties de la API documentation, API les intégrations et les autorisateurs dans une API exportation. Par défaut, les parties de la documentation sont incluses, mais les intégrations et les autorisateurs sont exclus lorsque vous exportez un. API La sortie par défaut d'une API exportation est adaptée à la distribution de la documentation.

Pour exporter la API documentation dans un API fichier JSON ouvert externe à l'aide de la API passerelle RESTAPI, soumettez la GET demande suivante :

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

Ici, l'x-amazon-apigateway-documentationobjet contient les parties de la documentation et les définitions des API entités contiennent les propriétés de documentation prises en charge par OpenAPI. Le résultat n'inclut pas les détails de l'intégration ou des mécanismes d'autorisation Lambda (anciennement appelés mécanismes d'autorisation personnalisés). Pour inclure les deux détails, définissez extensions=integrations,authorizers,documentation. Pour inclure les détails des intégrations, mais pas les mécanismes d'autorisation, définissez extensions=integrations,documentation.

Vous devez définir l'Accept:application/jsonen-tête de la demande pour afficher le résultat dans un JSON fichier. Pour produire la YAML sortie, remplacez l'en-tête de la demande parAccept:application/yaml.

À titre d'exemple, nous allons examiner un API qui expose une GET méthode simple sur la ressource racine (/). Quatre API entités sont définies dans un fichier de API définition ouvert, une pour chacun des RESPONSE types API MODELMETHOD,, et. API Une partie de la documentation a été ajoutée à chaque entité API, METHOD et RESPONSE. En appelant la commande d'exportation de documentation précédente, nous obtenons le résultat suivant, avec les parties de la documentation répertoriées dans l'x-amazon-apigateway-documentationobjet en tant qu'extension d'un fichier Open API 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"
}

Pour un attribut API compatible Open défini dans la properties carte d'une partie de documentation, API Gateway insère l'attribut dans la définition d'APIentité associée. Un attribut de x-something est une API extension Open standard. Cette extension est propagée dans la définition de l'APIentité. Par exemple, consultez l'attribut x-example pour la méthode GET. Un attribut tel ne foo fait pas partie de la API spécification Open et n'est pas injecté dans les définitions d'APIentités associées.

Si un outil de rendu de documentation (par exemple, Open API UI) analyse les définitions d'APIentités pour extraire les attributs de documentation, les attributs non API conformes properties à Open d'une instance DocumentationPart 'ne sont pas disponibles pour l'outil. Toutefois, si un outil de rendu de documentation analyse l'x-amazon-apigateway-documentationobjet pour obtenir du contenu, ou s'il appelle restapi:documentation-parts et documentationpart:by-id pour récupérer des parties de documentation depuis API Gateway, tous les attributs de documentation sont disponibles pour l'affichage par l'outil.

Pour exporter la documentation contenant les définitions d'APIentités contenant les détails de l'intégration vers un API fichier JSON Open, soumettez la GET demande suivante :

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

Pour exporter la documentation contenant les définitions d'APIentités contenant les détails des intégrations et des autorisateurs vers un API fichier YAML Open, soumettez la demande suivante : 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

Pour utiliser la console API Gateway afin d'exporter et de télécharger la documentation publiée d'unAPI, suivez les instructions figurant dansExporter REST API à l'aide de la console API Gateway.