Menu
Amazon API Gateway
Developer Guide

Representation of API Documentation in API Gateway

API Gateway API documentation consists of individual documentation parts associated with specific API entities that include API, resource, method, request, response, message parameters (i.e., path, query, header), as well as authorizers and models.

In API Gateway, a documentation part is represented by a DocumentationPart resource. The API documentation as a whole is represented by the DocumentationParts collection.

Documenting an API involves creating DocumentationPart instances, adding them to the DocumentationParts collection, and maintaining versions of the documentation parts as your API evolves.

Documentation Parts

A DocumentationPart resource is a JSON object that stores the documentation content applicable to an individual API entity. Its properties field contains the documentation content as a map of key-value pairs. Its location property identifies the associated API entity.

The shape of a content map is determined by you, the API developer. The value of a key-value pair can be a string, number, boolean, object, or array. The shape of the location object depends on the targeted entity type.

The DocumentationPart resource supports content inheritance: the documentation content of an API entity is applicable to children of that API entity. For more information about the definition of child entities and content inheritance, see Inherit Content from an API Entity of More General Specification.

Location of a Documentation Part

The location property of a DocumentationPart instance identifies an API entity to which the associated content applies. The API entity can be an API Gateway REST API resource, such as RestApi, Resource, Method, MethodResponse, Authorizer, or Model. The entity can also be a message parameter, such as a URL path parameter, a query string parameter, a request or response header parameter, a request or response body, or response status code.

To specify an API entity, set the type attribute of the location object to be one of API, AUTHORIZER, MODEL, RESOURCE, METHOD, PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER, or RESPONSE_BODY.

Depending on the type of an API entity, you might specify other location attributes, including method, name, path, and statusCode. Not all of these attributes are valid for a given API entity. For example, type, path, name, and statusCode are valid attributes of the RESPONSE entity; only type and path are valid location attributes of the RESOURCE entity. It is an error to include an invalid field in the location of a DocumentationPart for a given API entity.

Not all valid location fields are required. For example, type is both the valid and required location field of all API entities. However, method, path, and statusCode are valid but not required attributes for the RESPONSE entity. When not explicitly specified, a valid location field assumes its default value. The default path value is /, i.e., the root resource of an API. The default value of method, or statusCode is *, meaning any method, or status code values, respectively.

Content of a Documentation Part

The properties value is encoded as a JSON string. The properties value contains any information you choose to meet your documentation requirements. For example, the following is a valid content map:

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

To set it as a value of properties using the API Gateway REST API, encode this object as a JSON string:

Copy
"{\n\t\"info\": {\n\t\t\"description\": \"My first API with Amazon API Gateway.\"\n\t}, … \n}"

Although API Gateway accepts any valid JSON string as the content map, the content attributes are treated as two categories: those that can be recognized by Swagger and those that cannot. In the preceding example, info, description, and x-custom-info are recognized by Swagger as a standard Swagger object, property, or extension. In contrast, my-info is not compliant with the Swagger specification. API Gateway propagates Swagger-compliant content attributes into the API entity definitions from the associated DocumentationPart instances. API Gateway does not propagate the non-compliant content attributes into the API entity definitions.

As another example, here is DocumentationPart targeted for a Resource entity:

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

Here, both type and path are valid fields to identify the target of the RESOURCE type. For the root resource (/), you can omit the path field.

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

This is the same as the following DocumentationPart instance:

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

Inherit Content from an API Entity of More General Specifications

The default value of an optional location field provides a patterned description of an API entity. Using the default value in the location object, you can add a general description in the properties map to a DocumentationPart instance with this type of location pattern. API Gateway extracts the applicable Swagger documentation attributes from the DocumentationPart of the generic API entity and injects them into a specific API entity with the location fields matching the general location pattern, or matching the exact value, unless the specific entity already has a DocumentationPart instance associated with it. This behavior is also known as content inheritance from an API entity of more general specifications.

Content inheritance does not apply to API entities of the API, AUTHORIZER, METHOD, MODEL, REQUEST_BODY or RESOURCE type.

When an API entity matches more than one DocumentationPart's location pattern, the entity will inherit the documentation part with the location fields of the highest precedence and specificities. The order of precedence is path > statusCode. For matching with the path field, API Gateway chooses the entity with the most specific path value. The following table shows this with a few examples.

Case path statusCode name Remarks
1 /pets * id

Documentation associated with this location pattern will be inherited by entities matching the location pattern.

2 /pets 200 id

Documentation associated with this location pattern will be inherited by entities matching the location pattern when both Case 1 and Case 2 are matched, because Case 2 is more specific than Case 1.

3 /pets/petId * id

Documentation associated with this location pattern will be inherited by entities matching the location pattern when Cases 1, 2, and 3 are matched, because Case 3 has a higher precedence than Case 2 and is more specific than Case 1.

Here is another example to contrast a more generic DocumentationPart instance to a more specific one. The following general error message of "Invalid request error" is injected into the Swagger definitions of the 400 error responses, unless overridden.

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

With the following overwrite, the 400 responses to any methods on the /pets resource has a description of "Invalid petId specified" instead.

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

Valid Location Fields of DocumentationPart

The following table shows the valid and required fields as well as applicable default values of a DocumentationPart resource that is associated with a given type of API entities.

API entity

Valid location fields

Required location fields Default field values Inheritable Content
API
Copy
{ "location": { "type": "API" }, ... }
type N/A No
Resource
Copy
{ "location": { "type": "RESOURCE", "path": "resource_path" }, ... }
type The default value of path is /. No
Method
Copy
{ "location": { "type": "METHOD", "path": "resource_path", "method": "http_verb" }, ... }
type The default values of path and method are / and *, respectively. Yes, matching path by prefix and matching method of any values.
Query parameter
Copy
{ "location": { "type": "QUERY_PARAMETER", "path": "resource_path", "method": "HTTP_verb", "name": "query_parameter_name" }, ... }
type The default values of path and method are / and *, respectively. Yes, matching path by prefix and matching method by exact values.
Request body
Copy
{ "location": { "type": "REQUEST", "path": "resource_path", "method": "http_verb" }, ... }
type The default values of path, and method are /and *, respectively. Yes, matching path by prefix, and matching method by exact values.
Request header parameter
Copy
{ "location": { "type": "REQUEST_HEADER", "path": "resource_path", "method": "HTTP_verb", "name": "header_name" }, ... }
type, name The default values of path and method are / and *, respectively. Yes, matching path by prefix and matching method by exact values.
Request path parameter
Copy
{ "location": { "type": "PATH_PARAMETER", "path": "resource/{path_parameter_name}", "method": "HTTP_verb", "name": "path_parameter_name" }, ... }
type, name The default values of path and method are / and *, respectively. Yes, matching path by prefix and matching method by exact values.
Response
Copy
{ "location": { "type": "RESPONSE", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type The default values of path, method, and statusCode are /, * and *, respectively. Yes, matching path by prefix and matching method and statusCode by exact values.
Response header
Copy
{ "location": { "type": "RESPONSE_HEADER", "path": "resource_path", "method": "http_verb", "statusCode": "status_code", "name": "header_name" }, ... }
type, name The default values of path, method and statusCode are /, * and *, respectively. Yes, matching path by prefix and matching method, and statusCode by exact values.
Response body
Copy
{ "location": { "type": "RESPONSE_BODY", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type The default values of path, method and statusCode are /, * and *, respectively. Yes, matching path by prefix and matching method, and statusCode by exact values.
Authorizer
Copy
{ "location": { "type": "AUTHORIZER", "name": "authorizer_name" }, ... }
type N/A No
Model
Copy
{ "location": { "type": "MODEL", "name": "model_name" }, ... }
type N/A No

Documentation Versions

A documentation version is a snapshot of the DocumentationParts collection of an API and is tagged with a version identifier. Publishing the documentation of an API involves creating a documentation version, associating it with an API stage, and exporting that stage-specific version of the API documentation to an external Swagger file. In API Gateway, a documentation snapshot is represented as a DocumentationVersion resource.

As you update an API, you create new versions of the API. In API Gateway, you maintain all the documentation versions using the DocumentationVersions collection.