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.
# Documentation d’une API en utilisant l’API REST API Gateway
Dans cette section, nous décrivons la création et la gestion des parties de la documentation d’une API à l’aide de l’API REST API Gateway.
Avant de créer et de modifier la documentation d’une API, commencez par créer l’API. Dans cette section, nous utilisons l'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API comme exemple. Pour créer une API à l'aide de la console API Gateway, suivez les instructions de [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
**Topics**
+ [Documentation de l'entité `API`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api)
+ [Documentation d'une entité `RESOURCE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource)
+ [Documentation d'une entité `METHOD`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method)
+ [Documentation d'une entité `QUERY_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter)
+ [Documentation d'une entité `PATH_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter)
+ [Documentation d'une entité `REQUEST_BODY`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body)
+ [Documentation d'une entité `REQUEST_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header)
+ [Documentation d'une entité `RESPONSE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response)
+ [Documentation d'une entité `RESPONSE_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header)
+ [Documentation d'une entité `AUTHORIZER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer)
+ [Documentation d'une entité `MODEL`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model)
+ [Mise à jour de certaines parties de la documentation](#api-gateway-documenting-api-quick-start-with-restapi-update-content)
+ [Liste des parties de la documentation](#api-gateway-documenting-api-quick-start-with-restapi-list-parts)
## Documentation de l'entité `API`
Pour ajouter de la documentation pour une [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource pour l'entité API :
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
...
"id": "s2e5xf",
"location": {
"path": null,
"method": null,
"name": null,
"statusCode": null,
"type": "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Si la partie de la documentation a déjà été ajoutée, une réponse `409 Conflict` est renvoyée, avec le message d’erreur `Documentation part already exists for the specified location: type 'API'."`. Dans ce cas, vous devez appeler l’opération [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html).
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties",
"value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
} ]
}
```
La réponse positive renvoie un code de statut `200 OK` avec la charge utile contenant l'instance `DocumentationPart` mise à jour dans la charge utile.
## Documentation d'une entité `RESOURCE`
Pour ajouter de la documentation pour la ressource racine d'une API, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour la [ressource ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondante :
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "RESOURCE",
},
"properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
}
},
"id": "p76vqo",
"location": {
"path": "/",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Lorsque le chemin de ressource n’est pas spécifié, la ressource est supposée être la ressource racine. Vous pouvez ajouter `"path": "/"` à `properties` afin de rendre la spécification explicite.
Pour créer de la documentation pour une ressource enfant d'une API, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour la [ressource ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondante :
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Par exemple :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
}
},
"id": "qcht86",
"location": {
"path": "/pets",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Pour ajouter de la documentation pour une ressource enfant spécifiée par un paramètre de chemin, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour la [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) ressource :
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets/{petId}"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Par exemple :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
}
},
"id": "k6fpwb",
"location": {
"path": "/pets/{petId}",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
**Note**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance d'une `RESOURCE` entité ne peut être héritée par aucune de ses ressources enfants.
## Documentation d'une entité `METHOD`
Pour ajouter de la documentation pour une méthode d'une API, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour la ressource de [méthode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) correspondante :
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "METHOD",
"path" : "/pets",
"method" : "GET"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Si le champ `location.method` n’est pas précisé dans la demande précédente, c’est la méthode `ANY` qui est utilisée et représentée par le caractère générique `*`.
Pour mettre à jour le contenu de la documentation d’une entité `METHOD`, appelez l’opération [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) en fournissant un nouveau mappage `properties` :
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties",
"value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
} ]
}
```
La réponse positive renvoie un code de statut `200 OK` avec la charge utile contenant l'instance `DocumentationPart` mise à jour dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
}
```
## Documentation d'une entité `QUERY_PARAMETER`
Pour ajouter de la documentation pour un paramètre de requête, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour le `QUERY_PARAMETER` type, avec les champs valides de `path` et`name`.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "QUERY_PARAMETER",
"path" : "/pets",
"method" : "GET",
"name" : "page"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
}
},
"id": "h9ht5w",
"location": {
"path": "/pets",
"method": "GET",
"name": "page",
"statusCode": null,
"type": "QUERY_PARAMETER"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
Le mappage `properties` d’une partie de la documentation d’une entité `QUERY_PARAMETER` peut être hérité par l’une de ses entités enfants `QUERY_PARAMETER`. Par exemple, si vous ajoutez une ressource `treats` après `/pets/{petId}`, activez la méthode `GET` sur `/pets/{petId}/treats` et exposez le paramètre de demande `page`. Ce paramètre de demande enfant hérite pour `DocumentationPart` du mappage `properties` à partir du paramètre de demande du même nom de la méthode `GET /pets`, sauf si vous ajoutez explicitement une ressource `DocumentationPart` au paramètre de demande `page` de la méthode `GET /pets/{petId}/treats`.
## Documentation d'une entité `PATH_PARAMETER`
Pour ajouter de la documentation pour un paramètre de chemin, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource pour l'`PATH_PARAMETER`entité.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "PATH_PARAMETER",
"path" : "/pets/{petId}",
"method" : "*",
"name" : "petId"
},
"properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
}
},
"id": "ckpgog",
"location": {
"path": "/pets/{petId}",
"method": "*",
"name": "petId",
"statusCode": null,
"type": "PATH_PARAMETER"
},
"properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}"
}
```
## Documentation d'une entité `REQUEST_BODY`
Pour ajouter de la documentation pour le corps d'une demande, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource pour le corps de la demande.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "REQUEST_BODY",
"path" : "/pets",
"method" : "POST"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
}
},
"id": "kgmfr1",
"location": {
"path": "/pets",
"method": "POST",
"name": null,
"statusCode": null,
"type": "REQUEST_BODY"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
## Documentation d'une entité `REQUEST_HEADER`
Pour ajouter de la documentation pour un en-tête de demande, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource pour l'en-tête de demande.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "REQUEST_HEADER",
"path" : "/pets",
"method" : "GET",
"name" : "x-my-token"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
}
},
"id": "h0m3uf",
"location": {
"path": "/pets",
"method": "GET",
"name": "x-my-token",
"statusCode": null,
"type": "REQUEST_HEADER"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
## Documentation d'une entité `RESPONSE`
Pour ajouter de la documentation pour une réponse à un code de statut, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour la [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)ressource correspondante.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
}
},
"id": "lattew",
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
## Documentation d'une entité `RESPONSE_HEADER`
Pour ajouter de la documentation pour un en-tête de réponse, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource pour l'en-tête de réponse.
```
POST /restapis/restapi_id/documentation/parts 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
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Exemples :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
}
},
"id": "fev7j7",
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
}
```
La documentation de cet en-tête de réponse `Content-Type` est la documentation par défaut des en-têtes `Content-Type` de toutes les réponses de l’API.
## Documentation d'une entité `AUTHORIZER`
Pour ajouter de la documentation pour un autorisateur d'API, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour l'autorisateur spécifié.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "AUTHORIZER",
"name" : "myAuthorizer"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Par exemple :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
}
},
"id": "pw3qw3",
"location": {
"path": null,
"method": null,
"name": "myAuthorizer",
"statusCode": null,
"type": "AUTHORIZER"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
**Note**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance d'une `AUTHORIZER` entité ne peut être héritée par aucune de ses ressources enfants.
## Documentation d'une entité `MODEL`
La documentation d'une entité `MODEL` implique la création et la gestion d'instances `DocumentPart` pour le modèle et chacune des `properties` du modèle. Par exemple, le modèle `Error` qui est associé à chaque API par défaut a la définition de schéma suivante,
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
et exige deux instances `DocumentationPart`, une pour le `Model` et l'autre pour sa propriété `message` :
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
et
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
Lorsque l'API est exportée, les propriétés de `DocumentationPart` remplacent les valeurs dans le schéma d'origine.
Pour ajouter de la documentation pour un modèle d'API, ajoutez une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)ressource ciblée pour le modèle spécifié.
```
POST /restapis/restapi_id/documentation/parts 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
{
"location" : {
"type" : "MODEL",
"name" : "Pet"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Si l'opération réussit, elle renvoie une réponse `201 Created` contenant l'instance `DocumentationPart` nouvellement créée dans la charge utile. Par exemple :
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
}
},
"id": "lkn4uq",
"location": {
"path": null,
"method": null,
"name": "Pet",
"statusCode": null,
"type": "MODEL"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Répétez la même étape pour créer une DocumentationPart instance pour l'une des propriétés du modèle.
**Note**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance d'une `MODEL` entité ne peut être héritée par aucune de ses ressources enfants.
## Mise à jour de certaines parties de la documentation
Pour mettre à jour les parties de documentation de tout type d'entité API, soumettez une requête PATCH sur une [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance d'un identifiant de pièce spécifié afin de remplacer la `properties` carte existante par une nouvelle.
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "RESOURCE_PATH",
"value" : "NEW_properties_VALUE_AS_JSON_STRING"
} ]
}
```
La réponse positive renvoie un code de statut `200 OK` avec la charge utile contenant l'instance `DocumentationPart` mise à jour dans la charge utile.
Vous pouvez mettre à jour plusieurs parties de la documentation dans une seule demande `PATCH`.
## Liste des parties de la documentation
Pour répertorier les parties de documentation de tout type d'entité d'API, soumettez une requête GET sur une [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)collection.
```
GET /restapis/restapi_id/documentation/parts 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
```
La réponse positive renvoie un code de statut `200 OK` avec la charge utile contenant les instances `DocumentationPart` disponibles dans la charge utile.