Représentation de la documentation de l'API dans API Gateway - Amazon API Gateway
Parties de la documentationVersions de la documentation

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Représentation de la documentation de l'API dans API Gateway

La documentation de l'API API Gateway est composée de plusieurs parties de la documentation associées aux entités API spécifiques qui incluent l'API, la ressource, la méthode, la demande, la réponse, les paramètres de message (par exemple, le chemin d'accès, la requête, l'en-tête), ainsi que les mécanismes d'autorisation et les modèles.

Dans API Gateway, une partie de la documentation est représentée par une ressource DocumentationPart. La documentation de l'API dans son ensemble est représentée par la collection DocumentationParts.

La documentation d'une API consiste à créer des instances DocumentationPart, à les ajouter à la collection DocumentationParts et à gérer les versions des parties de la documentation au fur et à mesure de l'évolution de l'API.

Parties de la documentation

Une ressource DocumentationPart est un objet JSON qui stocke le contenu de la documentation applicable à une entité API individuelle. Son champ properties contient la documentation sous forme de mappage de paires clé-valeur. Sa propriété location identifie l'entité d'API associée.

La forme d'un mappage de contenu est déterminée par vous-même en tant que développeur de l'API. La valeur d'une paire clé-valeur peut être une chaîne, un nombre, une valeur booléenne, un objet ou un tableau. La forme de l'objet location varie selon le type d'entité ciblé.

La ressource DocumentationPart prend en charge l'héritage du contenu : le contenu de la documentation d'une entité d'API s'applique aux enfants de cette entité d'API. Pour plus d'informations sur la définition des entités enfants et sur l'héritage de contenu, consultez Héritage du contenu d'une entité d'API générale.

Emplacement de la partie d'une documentation

La propriété location d'une instance DocumentationPart identifie une entité d'API à laquelle le contenu associé s'applique. L'entité d'API peut être une ressource d'API REST API Gateway, par exemple RestApi, Resource, Method, MethodResponse, Authorizer ou Model. L'entité peut également être un paramètre de message, par exemple un paramètre de chemin d'accès d'URL, un paramètre de chaîne de requête, un paramètre de demande ou d'en-tête de réponse, un corps de demande ou de réponse, ou un code de statut de réponse.

Pour spécifier une entité d'API, définissez l'attribut type de l'objet location comme API, AUTHORIZER, MODEL, RESOURCE, METHOD, PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER ou RESPONSE_BODY.

Selon le type d'une entité d'API, vous pouvez spécifier d'autres attributs location, dont method, name, path et statusCode. Certains attributs ne sont pas valides pour une entité d'API donnée. Par exemple, type, path, name et statusCode sont des attributs valides pour l'entité RESPONSE ; mais seuls type et path sont des attributs d'emplacement valides pour l'entité RESOURCE. C'est une erreur d'inclure un champ non valide dans l'attribut location d'une DocumentationPart pour une entité d'API donnée.

Tous les champs location valides ne sont pas obligatoires. Par exemple, type est le champ valide et obligatoire location de toutes les entités d'API. Toutefois, method, path et statusCode sont des attributs valides mais facultatifs pour l'entité RESPONSE. Lorsqu'il n'est pas spécifié explicitement, un champ location valide se voit attribuer sa valeur par défaut. La valeur par défaut de path est /, c'est-à-dire la ressource racine d'une API. La valeur par défaut de method ou statusCode est *, c'est-à-dire n'importe quelle méthode ou valeur de code de statut, respectivement.

Contenu d'une partie de la documentation

La valeur properties est codée sous forme de chaîne JSON. Le valeur properties contient les informations que vous choisissez afin de répondre à vos besoins en documentation. Par exemple, ce qui suit est un mappage de contenu valide : 

{
  "info": {
    "description": "My first API with Amazon API Gateway."
  },
  "x-custom-info" : "My custom info, recognized by OpenAPI.",
  "my-info" : "My custom info not recognized by OpenAPI."
}

Même si API Gateway accepte une chaîne JSON valide en tant que mappage de contenu, les attributs de contenu sont traités selon deux catégories : ceux qui peuvent être reconnus par OpenAPI et ceux qui ne le peuvent pas. Dans l'exemple précédent, info, description et x-custom-info sont reconnus par OpenAPI comme objet, propriété ou extension OpenAPI standard. En revanche, my-info n'est pas conforme à la spécification OpenAPI. API Gateway diffuse les attributs de contenu conformes à OpenAPI dans les définitions d'entité API à partir des instances DocumentationPart associées. API Gateway ne diffuse pas les attributs de contenu non conformes à la définition d'entité d'API.

Voici un autre exemple, DocumentationPart ciblé pour une entité Resource :

{
    "location" : {
        "type" : "RESOURCE",
        "path": "/pets"
    },
    "properties" : {
        "summary" : "The /pets resource represents a collection of pets in PetStore.",
        "description": "... a child resource under the root...",
    }
}

Ici, type et path sont des champs valides pour identifier la cible du type RESOURCE. Pour la ressource racine (/), vous pouvez ignorer le champ path.

{
    "location" : {
        "type" : "RESOURCE"
    },
    "properties" : {
        "description" : "The root resource with the default path specification."
    }
}

C'est identique à l'instance DocumentationPart suivante :

{
    "location" : {
        "type" : "RESOURCE",
        "path": "/"
    },
    "properties" : {
        "description" : "The root resource with an explicit path specification"
    }
}

Héritage du contenu de spécifications plus générales d'une entité d'API

La valeur par défaut d'un champ location facultatif fournit la description de modèle d'une entité d'API. À l'aide de la valeur par défaut de l'objet location, vous pouvez ajouter une description générale dans le mappage properties à une instance DocumentationPart avec ce type de modèle location. API Gateway extrait les attributs de documentation applicables à partir du champ DocumentationPart de l'entité API générique et les insère dans une entité API spécifique avec les champs location correspondant au modèle général location ou correspondant à la valeur exacte, à moins que l'entité spécifique n'ait déjà une instance DocumentationPart associée. Ce comportement est également connu sous le nom d'héritage de contenu de spécifications plus générales à partir d'une entité d'API.

L'héritage de contenu ne s'applique pas à certains types d'entités d'API. Consultez le tableau ci-dessous pour plus d'informations.

Lorsqu'une entité d'API correspond à plusieurs modèles d'emplacement de DocumentationPart, l'entité hérite de la partie de la documentation avec les champs d'emplacement ayant la priorité et les spécificités les plus élevés. L'ordre de priorité est path > statusCode. Pour que cela corresponde au champ path, API Gateway choisit l'entité ayant la valeur de chemin d'accès la plus spécifique. Le tableau suivant présente quelques exemples.

Cas path statusCode name Remarques
1 /pets * id

La documentation associée à ce modèle d'emplacement sera héritée par les entités correspondant au modèle d'emplacement.
2 /pets 200 id

La documentation associée à ce modèle d'emplacement sera héritée par les entités correspondant au modèle d'emplacement lorsque les cas 1 et 2 font l'objet d'une correspondance car le cas 2 est plus spécifique que le cas 1.

3 /pets/petId * id

La documentation associée à ce modèle d'emplacement est héritée par les entités correspondant au modèle d'emplacement lorsque les cas 1, 2 et 3 font l'objet d'une correspondance, car le cas 3 a une priorité plus élevée que le cas 2 et il est plus spécifique que le cas 1.

Voici un autre exemple dont le but est de comparer une instance DocumentationPart plus générique à une instance plus spécifique. Le message d'erreur générale "Invalid request error" est ajouté aux définitions OpenAPI des réponses d'erreur 400, à moins qu'il ne soit remplacé. 

{
    "location" : {
        "type" : "RESPONSE",
        "statusCode": "400"
    },
    "properties" : {
        "description" : "Invalid request error."
    }"
}

Avec le remplacement suivant, les réponses 400 à toutes les méthodes sur la ressource /pets ont une description "Invalid petId specified" à la place. 

{
    "location" : {
        "type" : "RESPONSE",
        "path": "/pets",
        "statusCode": "400"
    },
    "properties" : "{
        "description" : "Invalid petId specified."
    }"
}

Champs d'emplacement valides DocumentationPart

Le tableau suivant montre les champs valides et obligatoires, ainsi que les valeurs par défaut applicables d'une ressource DocumentationPart associée à un type donné d'entités API.

Entité de l'API

Champs d'emplacement valides

 Champs d'emplacement obligatoires Valeurs de champ par défaut Contenu pouvant être hérité
API 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
 type S/O Non
Ressource 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
 type La valeur par défaut de path est /. Non
Method 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type Les valeurs par défaut de path et method sont / et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method quelle que soit la valeur.
Paramètre de la demande 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
 type Les valeurs par défaut de path et method sont / et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method pour des valeurs exactes.
Corps de la demande 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type Les valeurs par défaut de path et method sont / et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method pour des valeurs exactes.
Paramètre d'en-tête de la demande 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
 type, name Les valeurs par défaut de path et method sont / et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method pour des valeurs exactes.
Paramètre de chemin d'accès de la demande 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
 type, name Les valeurs par défaut de path et method sont / et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method pour des valeurs exactes.
Réponse 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type Les valeurs par défaut de path, method et statusCode sont /, * et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method et statusCode pour des valeurs exactes.
En-tête de réponse 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
 type, name Les valeurs par défaut de path, method et statusCode sont /, * et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method et statusCode pour des valeurs exactes.
Corps de la réponse 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type Les valeurs par défaut de path, method et statusCode sont /, * et *, respectivement. Oui, correspondance de path par préfixe et correspondance de method et statusCode pour des valeurs exactes.
Mécanisme d'autorisation 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
 type S/O Non
Modèle 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
 type S/O Non

Versions de la documentation

Une version de la documentation est un instantané de la collection DocumentationParts d'une API et elle est référencée par un identifiant de version. La publication de la documentation d'une API implique la création d'une version de documentation, son association à une étape de l'API et l'exportation cette version spécifique à l'étape de la documentation de l'API dans un fichier OpenAPI externe. Dans API Gateway, un instantané de la documentation est représenté sous forme d'une ressource DocumentationVersion.

Lorsque vous mettez à jour une API, vous créez de nouvelles versions de cette dernière. Dans API Gateway, vous gérez toutes les versions de la documentation à l'aide de la collection DocumentationVersions.