Documentation d’une API en utilisant l’API REST API Gateway

Mode de mise au point

Documentation d’une API en utilisant l’API REST API Gateway - Amazon 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’API PetStore à titre d’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.

Rubriques

Documentation de l’entité API
Documentation d’une entité RESOURCE
Documentation d’une entité METHOD
Documentation d’une entité QUERY_PARAMETER
Documentation d’une entité PATH_PARAMETER
Documentation d’une entité REQUEST_BODY
Documentation d’une entité REQUEST_HEADER
Documentation d’une entité RESPONSE
Documentation d’une entité RESPONSE_HEADER
Documentation d’une entité AUTHORIZER
Documentation d’une entité MODEL
Mise à jour de certaines parties de la documentation
Liste des parties de la documentation

Documentation de l’entité `API`

Pour ajouter la documentation d’une API, ajoutez une ressource DocumentationPart 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.


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 une documentation relative à la ressource racine d’une API, ajoutez une ressource DocumentationPart ciblée pour la ressource Resource 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 une documentation relative à la ressource enfant d’une API, ajoutez une ressource DocumentationPart ciblée pour la ressource Resource 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. 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/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 une documentation relative à une ressource enfant spécifiée par un paramètre de chemin d’accès, ajoutez une ressource DocumentationPart ciblée pour la ressource Resource :


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. 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/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’instance DocumentationPart d’une entité RESOURCE ne peut pas être héritée par l’une de ses ressources enfants.

Documentation d’une entité `METHOD`

Pour ajouter une documentation relative à une méthode d’API, ajoutez une ressource DocumentationPart ciblée pour la ressource Method 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 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 une documentation relative à un paramètre de requête de la demande, ajoutez une ressource DocumentationPart ciblée pour le type QUERY_PARAMETER, 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 une documentation relative à un paramètre de chemin d’accès, ajoutez une ressource DocumentationPart pour l’entité PATH_PARAMETER.


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 une documentation relative au corps de la demande, ajoutez une ressource DocumentationPart 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 une documentation relative à un en-tête de demande, ajoutez une ressource DocumentationPart pour l’en-tête 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_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 une documentation relative à la réponse d’un code de statut, ajoutez une ressource DocumentationPart ciblée pour la ressource MethodResponse 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 une documentation relative à un en-tête de réponse, ajoutez une ressource DocumentationPart 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 une documentation relative au mécanisme d’autorisation d’API, ajoutez une ressource DocumentationPart ciblée pour le mécanisme d’autorisation 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. 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/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’instance DocumentationPart d’une entité AUTHORIZER ne peut pas être héritée par l’une 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"
  }
}


{
  "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 une documentation relative à un modèle d’API, ajoutez une ressource DocumentationPart 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. 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/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 les mêmes étapes afin de créer une instance DocumentationPart pour les propriétés du modèle.

Note

L’instance DocumentationPart d’une entité MODEL ne peut pas être héritée par l’une de ses ressources enfants.

Mise à jour de certaines parties de la documentation

Pour mettre à jour certaines parties de la documentation pour tous les types d’entités de l’API, soumettez une demande PATCH sur une instance DocumentationPart d’un identifiant de partie spécifié pour remplacer le mappage properties existant par un nouveau mappage.


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 établir une liste des parties de la documentation de tous les types d’entités de l’API, soumettez une demande GET sur une collection DocumentationParts.


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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Publication de la documentation de l’API à l’aide de la console API Gateway

Publication de la documentation de l’API à l’aide de l’API REST

Sur cette page

Sélectionner vos préférences de cookies

Personnaliser les préférences de cookies

Essentiels

Performances

Fonctionnels

Publicitaires

Impossible d'enregistrer les préférences concernant les cookies

Documentation d’une API en utilisant l’API REST API Gateway

Rubriques

Documentation de l’entité `API`

Documentation d’une entité `RESOURCE`

Note

Documentation d’une entité `METHOD`

Documentation d’une entité `QUERY_PARAMETER`

Documentation d’une entité `PATH_PARAMETER`

Documentation d’une entité `REQUEST_BODY`

Documentation d’une entité `REQUEST_HEADER`

Documentation d’une entité `RESPONSE`

Documentation d’une entité `RESPONSE_HEADER`

Documentation d’une entité `AUTHORIZER`

Note

Documentation d’une entité `MODEL`

Note

Mise à jour de certaines parties de la documentation

Liste des parties de la documentation

Sur cette page

Related resources

Cette page vous a-t-elle été utile ?

Related resources

Rubrique suivante :

Rubrique précédente :

Avez-vous besoin d’aide ?

Sélectionner vos préférences de cookies

Documentation d’une API en utilisant l’API REST API Gateway

Rubriques

Documentation de l’entité API

Documentation d’une entité RESOURCE

Note

Documentation d’une entité METHOD

Documentation d’une entité QUERY_PARAMETER

Documentation d’une entité PATH_PARAMETER

Documentation d’une entité REQUEST_BODY

Documentation d’une entité REQUEST_HEADER

Documentation d’une entité RESPONSE

Documentation d’une entité RESPONSE_HEADER

Documentation d’une entité AUTHORIZER

Note

Documentation d’une entité MODEL

Note

Mise à jour de certaines parties de la documentation

Liste des parties de la documentation

Sur cette page

Related resources

Cette page vous a-t-elle été utile ?

Related resources

Rubrique suivante :

Rubrique précédente :

Avez-vous besoin d’aide ?

Documentation de l’entité `API`

Documentation d’une entité `RESOURCE`

Documentation d’une entité `METHOD`

Documentation d’une entité `QUERY_PARAMETER`

Documentation d’une entité `PATH_PARAMETER`

Documentation d’une entité `REQUEST_BODY`

Documentation d’une entité `REQUEST_HEADER`

Documentation d’une entité `RESPONSE`

Documentation d’une entité `RESPONSE_HEADER`

Documentation d’une entité `AUTHORIZER`

Documentation d’une entité `MODEL`