Publish API documentation using the API Gateway REST API
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.
Topics
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:
POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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:
POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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, version1.0.0.
PATCH /restapis/restapi_id/documentation/versions/versionHTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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.
GET /restapis/<restapi_id>/documentation/versions/1.0.0 HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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:
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAMEHost: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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" }] }
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 Amazon 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 OpenAPI file using the API Gateway
REST API, submit the following GET request:
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:YYYYMMDDTttttttZAuthorization: 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 OpenAPI. The output does not include details
of integration or Lambda authorizers (formerly known as 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 an
OpenAPI 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
OpenAPI file.
For an OpenAPI-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- is a standard OpenAPI
extension. This extension gets propagated into the API entity definition. For
example, see the somethingx-example attribute for the GET method. An attribute like foo is not part of the OpenAPI specification and is not injected into
its associated API entity definitions.
If a documentation-rendering tool (e.g., OpenAPI UIproperties 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 OpenAPI file, submit the following GET request:
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:YYYYMMDDTttttttZAuthorization: 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 OpenAPI file, submit the following GET request:
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:YYYYMMDDTttttttZAuthorization: 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 REST API using the API Gateway console.