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'PetStoreAPI 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.

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 de la documentation pour une API, ajoutez une DocumentationPartressource 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 de la documentation pour la ressource racine d'une API, ajoutez une DocumentationPartressource ciblée pour la ressource 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" : {
       "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 DocumentationPartressource ciblée pour la ressource 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" : {
         "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 de la documentation pour une ressource enfant spécifiée par un paramètre de chemin, ajoutez une DocumentationPartressource ciblée pour la ressource 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. 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'DocumentationPartinstance 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 DocumentationPartressource ciblée pour la ressource de méthode 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 de la documentation pour un paramètre de requête, ajoutez une DocumentationPartressource ciblée pour le QUERY_PARAMETER type, avec les champs valides de path etname.


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 DocumentationPartressource pour l'PATH_PARAMETERentité.


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 DocumentationPartressource 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 DocumentationPartressource 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 DocumentationPartressource ciblée pour la MethodResponseressource 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 DocumentationPartressource 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 DocumentationPartressource 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. 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'DocumentationPartinstance 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"
  }
}


{
  "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 DocumentationPartressource 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 la même étape pour créer une DocumentationPart instance pour l'une des propriétés du modèle.

Note

L'DocumentationPartinstance 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 DocumentationPartinstance 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 DocumentationPartscollection.


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

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

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`