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 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource. La documentation de l'API dans son ensemble est représentée par la [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)collection. 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. **Topics** + [Parties de la documentation](#api-gateway-documenting-api-content-representation-documentation-parts) + [Versions de la documentation](#api-gateway-documenting-api-content-representation-documentation-versions) ## Parties de la documentation Une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource est un objet JSON qui stocke le contenu de la documentation applicable à une entité d'API individuelle. Cela inclut tout le contenu UTF-8 et toutes les principales langues de localisation de votre documentation. 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](#api-gateway-documenting-api-content-inheritance). ### Emplacement de la partie d’une documentation La propriété de [localisation](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) d'une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance identifie une entité d'API à laquelle s'applique le contenu associé. L'entité API peut être une ressource d'API REST API Gateway, telle que [Resource [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) ou [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). 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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) et [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#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 | \$1 | 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 | \$1 | 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 indique les champs valides et obligatoires ainsi que les valeurs par défaut applicables d'une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | S/O | Non | | [Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | La valeur par défaut de path est /. | Non | | [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | Les valeurs par défaut de path et method sont / et \$1, 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 \$1, 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 \$1, 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 \$1, 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 \$1, 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 /, \$1 et \$1, 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 /, \$1 et \$1, 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 /, \$1 et \$1, respectivement. | Oui, correspondance de path par préfixe et correspondance de method et statusCode pour des valeurs exactes. | | [Mécanisme d’autorisation](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | S/O | Non | | [Modèle](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | S/O | Non | ## Versions de la documentation Une version de documentation est un instantané de la [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)collection d'une API et est étiquetée avec 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 documentation est représenté sous forme de [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)ressource. 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 documentation à l'aide de la [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)collection.