documentation_parts

Creates, updates, deletes, gets or lists a documentation_parts resource.

Overview

Name	documentation_parts
Type	Resource
Id	aws.apigateway.documentation_parts

Fields

The following fields are returned by SELECT queries:

get_documentation_part

Name	Datatype	Description
id	string	The DocumentationPart identifier, generated by API Gateway when the DocumentationPart is created.
location	object	Specifies the target API entity to which the documentation applies.
properties_	string	A content map of API-specific key-value pairs describing the targeted API entity. The map must be encoded as a JSON string, e.g., "{ "description": "The API does ..." }". Only OpenAPI-compliant documentation-related fields from the properties map are exported and, hence, published as part of the API entity definitions, while the original documentation parts are exported in a OpenAPI extension of x-amazon-apigateway-documentation.

get_documentation_parts

Name	Datatype	Description
id	string	The DocumentationPart identifier, generated by API Gateway when the DocumentationPart is created.
location	object	Specifies the target API entity to which the documentation applies.
properties_	string	A content map of API-specific key-value pairs describing the targeted API entity. The map must be encoded as a JSON string, e.g., "{ "description": "The API does ..." }". Only OpenAPI-compliant documentation-related fields from the properties map are exported and, hence, published as part of the API entity definitions, while the original documentation parts are exported in a OpenAPI extension of x-amazon-apigateway-documentation.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_documentation_part	select	restapi_id, part_id, region		Gets a documentation part.
get_documentation_parts	select	restapi_id, region	type, name, path, position, limit, locationStatus	Gets documentation parts.
create_documentation_part	insert	restapi_id, region, location, properties		Creates a documentation part.
update_documentation_part	update	restapi_id, part_id, region		Updates a documentation part.
delete_documentation_part	delete	restapi_id, part_id, region		Deletes a documentation part
import_documentation_parts	exec	restapi_id, region, body	mode, failonwarnings	Imports documentation parts

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
part_id	string	The identifier of the to-be-deleted documentation part.
region	string	AWS region (default: us-east-1)
restapi_id	string	The string identifier of the associated RestApi.
failonwarnings	boolean	A query parameter to specify whether to rollback the documentation importation (true) or not (false) when a warning is encountered. The default value is false.
limit	integer	The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
locationStatus	string	The status of the API documentation parts to retrieve. Valid values are DOCUMENTED for retrieving DocumentationPart resources with content and UNDOCUMENTED for DocumentationPart resources without content.
mode	string	A query parameter to indicate whether to overwrite (overwrite) any existing DocumentationParts definition or to merge (merge) the new definition into the existing one. The default value is merge.
name	string	The name of API entities of the to-be-retrieved documentation parts.
path	string	The path of API entities of the to-be-retrieved documentation parts.
position	string	The current pagination position in the paged result set.
type	string	The type of API entities of the to-be-retrieved documentation parts.

SELECT examples

get_documentation_part

Gets a documentation part.

SELECT
id,
location,
properties_
FROM aws.apigateway.documentation_parts
WHERE restapi_id = '{{ restapi_id }}' -- required
AND part_id = '{{ part_id }}' -- required
AND region = '{{ region }}' -- required
;

get_documentation_parts

Gets documentation parts.

SELECT
id,
location,
properties_
FROM aws.apigateway.documentation_parts
WHERE restapi_id = '{{ restapi_id }}' -- required
AND region = '{{ region }}' -- required
AND type = '{{ type }}'
AND name = '{{ name }}'
AND path = '{{ path }}'
AND position = '{{ position }}'
AND limit = '{{ limit }}'
AND locationStatus = '{{ locationStatus }}'
;

INSERT examples

create_documentation_part

Creates a documentation part.

INSERT INTO aws.apigateway.documentation_parts (
location,
properties,
restapi_id,
region
)
SELECT 
'{{ location }}' /* required */,
'{{ properties }}' /* required */,
'{{ restapi_id }}',
'{{ region }}'
RETURNING
id,
location,
properties_
;

Manifest

# Description fields are for documentation purposes
- name: documentation_parts
props:
  - name: restapi_id
    value: "{{ restapi_id }}"
    description: Required parameter for the documentation_parts resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the documentation_parts resource.
  - name: location
    description: |
      Specifies the target API entity to which the documentation applies.
    value:
      type_: "{{ type_ }}"
      path: "{{ path }}"
      method: "{{ method }}"
      statusCode: "{{ statusCode }}"
      name: "{{ name }}"
  - name: properties
    value: "{{ properties }}"

UPDATE examples

update_documentation_part

Updates a documentation part.

UPDATE aws.apigateway.documentation_parts
SET 
patchOperations = '{{ patchOperations }}'
WHERE 
restapi_id = '{{ restapi_id }}' --required
AND part_id = '{{ part_id }}' --required
AND region = '{{ region }}' --required
RETURNING
id,
location,
properties_;

DELETE examples

delete_documentation_part

Deletes a documentation part

DELETE FROM aws.apigateway.documentation_parts
WHERE restapi_id = '{{ restapi_id }}' --required
AND part_id = '{{ part_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

import_documentation_parts

Imports documentation parts

EXEC aws.apigateway.documentation_parts.import_documentation_parts 
@restapi_id='{{ restapi_id }}' --required, 
@region='{{ region }}' --required, 
@mode='{{ mode }}', 
@failonwarnings={{ failonwarnings }} 
@@json=
'{
"body": "{{ body }}"
}'
;