Menu
Amazon API Gateway
Developer Guide

Publish API Documentation

To publish the documentation for an API, create, update, or get a documentation snapshot, and then associate the documentation snapshot with an API stage. When creating a documentation snapshot, you can also associate it with an API stage at the same time.

Create a Documentation Snapshot and Associate it with an API Stage

To create a snapshot of an API's documentation parts and associate it with an API stage at the same time, submit the following POST request:

Copy
POST /restapis/restapi_id/documentation/versions 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 { "documentationVersion" : "1.0.0", "stageName": "prod", "description" : "My API Documentation v1.0.0" }

If successful, the operation returns a 200 OK response, containing the newly created DocumentationVersion instance as the payload.

Alternatively, you can create a documentation snapshot without associating it with an API stage first and then call restapi:update to associate the snapshot with a specified API stage. You can also update or query an existing documentation snapshot and then update its stage association. We show the steps in the next four sections.

Create a Documentation Snapshot

To create a snapshot of an API's documentation parts, create a new DocumentationVersion resource and add it to the DocumentationVersions collection of the API:

Copy
POST /restapis/restapi_id/documentation/versions 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 { "documentationVersion" : "1.0.0", "description" : "My API Documentation v1.0.0" }

If successful, the operation returns a 200 OK response, containing the newly created DocumentationVersion instance as the payload.

Update a Documentation Snapshot

You can only update a documentation snapshot by modifying the description property of the corresponding DocumentationVersion resource. The following example shows how to update the description of the documentation snapshot as identified by its version identifier, version, e.g., 1.0.0.

Copy
PATCH /restapis/restapi_id/documentation/versions/version 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": "/description", "value": "My API for testing purposes." }] }

If successful, the operation returns a 200 OK response, containing the updated DocumentationVersion instance as the payload.

Get a Documentation Snapshot

To get a documentation snapshot, submit a GET request against the specified DocumentationVersion resource. The following example shows how to get a documentation snapshot of a given version identifier, 1.0.0.

Copy
GET /restapis/<restapi_id>/documentation/versions/1.0.0 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

Associate a Documentation Snapshot with an API Stage

To publish the API documentation, associate a documentation snapshot with an API stage. You must have already created an API stage before associating the documentation version with the stage.

To associate a documentation snapshot with an API stage using the API Gateway REST API, call the stage:update operation to set the desired documentation version on the stage.documentationVersion property:

Copy
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME 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": "/documentationVersion", "value": "VERSION_IDENTIFIER" }] }

The following procedure describes how to publish a documentation version.

To publish a documentation version using the API Gateway console

  1. Choose Documentation for the API from the main navigation pane in the API Gateway console.

  2. Choose Publish Documentation in the Documentation pane.

  3. Set up the publication:

    1. Choose an available name for Stage.

    2. Type a version identifier, e.g., 1.0.0, in Version.

    3. Optionally, provide a description about the publication in Description.

  4. Choose Publish.

You can now proceed to download the published documentation by exporting the documentation to an external Swagger file.

Download a Documentation Snapshot Associated with a Stage

After a version of the documentation parts is associated with a stage, you can export the documentation parts together with the API entity definitions, to an external file, using the API Gateway console, the API Gateway REST API, one of its SDKs, or the AWS CLI for API Gateway. The process is the same as for exporting the API. The exported file format can be JSON or YAML.

Using the API Gateway REST API, you can also explicitly set the extension=documentation,integrations,authorizers query parameter to include the API documentation parts, API integrations and authorizers in an API export. By default, documentation parts are included, but integrations and authorizers are excluded, when you export an API. The default output from an API export is suited for distribution of the documentation.

To export the API documentation in an external JSON Swagger file using the API Gateway REST API, submit the following GET request:

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1 Accept: application/json 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

Here, the x-amazon-apigateway-documentation object contains the documentation parts and the API entity definitions contains the documentation properties supported by Swagger. The output does not include details of integration or custom authorizers. To include both details, set extensions=integrations,authorizers,documentation. To include details of integrations but not of authorizers, set extensions=integrations,documentation.

You must set the Accept:application/json header in the request to output the result in a JSON file. To produce the YAML output, change the request header to Accept:application/yaml.

As an example, we will look at an API that exposes a simple GET method on the root resource (/). This API has four API entities defined in a Swagger definition file, one for each of the API, MODEL, METHOD, and RESPONSE types. A documentation part has been added to each of the API, METHOD, and RESPONSE entities. Calling the preceding documentation-exporting command, we get the following output, with the documentation parts listed within the x-amazon-apigateway-documentation object as an extension to a standard Swagger file.

Copy
{ "swagger" : "2.0", "info" : { "description" : "api info description", "version" : "2016-11-22T22:39:14Z", "title" : "doc", "x-bar" : "api info x-bar" }, "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com", "basePath" : "/test", "schemes" : [ "https" ], "paths" : { "/" : { "get" : { "description" : "Method description.", "produces" : [ "application/json" ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/Empty" } } }, "x-example" : "x- Method example" }, "x-bar" : "resource x-bar" } }, "definitions" : { "Empty" : { "type" : "object", "title" : "Empty Schema" } }, "x-amazon-apigateway-documentation" : { "version" : "1.0.0", "createdDate" : "2016-11-22T22:41:40Z", "documentationParts" : [ { "location" : { "type" : "API" }, "properties" : { "description" : "api description", "foo" : "api foo", "x-bar" : "api x-bar", "info" : { "description" : "api info description", "version" : "api info version", "foo" : "api info foo", "x-bar" : "api info x-bar" } } }, { "location" : { "type" : "METHOD", "method" : "GET" }, "properties" : { "description" : "Method description.", "x-example" : "x- Method example", "foo" : "Method foo", "info" : { "version" : "method info version", "description" : "method info description", "foo" : "method info foo" } } }, { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "resource description", "foo" : "resource foo", "x-bar" : "resource x-bar", "info" : { "description" : "resource info description", "version" : "resource info version", "foo" : "resource info foo", "x-bar" : "resource info x-bar" } } } ] }, "x-bar" : "api x-bar" }

For a Swagger-compliant attribute defined in the properties map of a documentation part, API Gateway inserts the attribute into the associated API entity definition. An attribute of x-something is a standard Swagger extension. This extension gets propagated into the API entity definition. For example, see the x-example attribute for the GET method. An attribute like foo is not part of the Swagger specification and is not injected into its associated API entity definitions.

If a documentation-rendering tool (e.g., Swagger UI) parses the API entity definitions to extract documentation attributes, any non Swagger-compliant properties attributes of a DocumentationPart' instance are not available for the tool. However, if a documentation-rendering tool parses the x-amazon-apigateway-documentation object to get content, or if the tool calls restapi:documentation-parts and documenationpart:by-id to retrieve documentation parts from API Gateway, all the documentation attributes are available for the tool to display.

To export the documentation with API entity definitions containing integration details to a JSON Swagger file, submit the following GET request:

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1 Accept: application/json 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

To export the documentation with API entity definitions containing details of integrations and authorizers to a YAML Swagger file, submit the following GET request:

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1 Accept: application/yaml 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

To use the API Gateway console to export and download the published documentation of an API, follow the instructions in Export API Using the API Gateway Console.