Import API documentation
As with importing API entity definitions, you can import documentation parts from an external OpenAPI file into an API in API Gateway. You specify the to-be-imported documentation parts within the x-amazon-apigateway-documentation object extension in a valid OpenAPI definition file. Importing documentation does not alter the existing API entity definitions.
You have an option to merge the newly specified documentation parts into existing
documentation parts in API Gateway or to overwrite the existing documentation parts. In the
MERGE mode, a new documentation part defined in the
OpenAPI file is added to the DocumentationParts
collection of the API. If an imported DocumentationPart
already exists, an imported attribute replaces the existing one if the two are
different. Other existing documentation attributes remain unaffected. In the OVERWRITE mode, the entire DocumentationParts collection is replaced according to the imported OpenAPI
definition file.
Importing documentation parts using the API Gateway REST API
To import API documentation using the API Gateway REST API, call the documentationpart:import operation. The following example shows how to
overwrite existing documentation parts of an API with a single GET / method, returning a 200 OK response when successful.
When successful, this request returns a 200 OK response containing the imported
DocumentationPartId in the payload.
{ "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] }
In addition, you can also call restapi:import or
restapi:put,
supplying the documentation parts in the x-amazon-apigateway-documentation object as part of the input OpenAPI
file of the API definition. To exclude the documentation parts from the API import,
set ignore=documentation in the request query
parameters.
Importing documentation parts using the API Gateway console
The following instructions describe how to import documentation parts.
To use the console to import documentation parts of an API from an external file
-
In the main navigation pane, choose Documentation.
-
Choose Import.
-
If you have existing documentation, select to either Overwrite or Merge your new documentation.
-
Choose Choose file to load a file from a drive, or enter file contents into the file view. For an example, see the payload of the example request in Importing documentation parts using the API Gateway REST API.
-
Choose how to handle warnings on import. Select either Fail on warnings or Ignore warnings. For more information, see Errors and warnings from importing your API into API Gateway.
-
Choose Import.
