docs(clients): add script to write examples for commands (#4486)

* docs(clients): add script to write examples for commands

* docs(clients): codegen for command examples

Author: kuhe

.gitignore

@@ -33,6 +33,7 @@ dist
 
 codegen/**/build
 codegen/**/build-single
+codegen/sdk-codegen/aws-models-examples
 codegen/sdk-codegen/smithy-build.json
 codegen/sdk-codegen/smithy-build-*.json
 .gradle

clients/client-appconfig/src/commands/CreateApplicationCommand.ts

@@ -54,6 +54,25 @@ export interface CreateApplicationCommandOutput extends Application, __MetadataB
  * @see {@link CreateApplicationCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To create an application
+ * ```javascript
+ * // The following create-application example creates an application in AWS AppConfig.
+ * const input = {
+ *   "Description": "An application used for creating an example.",
+ *   "Name": "example-application"
+ * };
+ * const command = new CreateApplicationCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "Description": "An application used for creating an example.",
+ *   "Id": "339ohji",
+ *   "Name": "example-application"
+ * }
+ * *\/
+ * // example id: to-create-an-application-1632264511615
+ * ```
+ *
  */
 export class CreateApplicationCommand extends $Command<
   CreateApplicationCommandInput,

clients/client-appconfig/src/commands/CreateConfigurationProfileCommand.ts

@@ -89,6 +89,29 @@ export interface CreateConfigurationProfileCommandOutput extends ConfigurationPr
  * @see {@link CreateConfigurationProfileCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To create a configuration profile
+ * ```javascript
+ * // The following create-configuration-profile example creates a configuration profile using a configuration stored in Parameter Store, a capability of Systems Manager.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "LocationUri": "ssm-parameter://Example-Parameter",
+ *   "Name": "Example-Configuration-Profile",
+ *   "RetrievalRoleArn": "arn:aws:iam::111122223333:role/Example-App-Config-Role"
+ * };
+ * const command = new CreateConfigurationProfileCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ApplicationId": "339ohji",
+ *   "Id": "ur8hx2f",
+ *   "LocationUri": "ssm-parameter://Example-Parameter",
+ *   "Name": "Example-Configuration-Profile",
+ *   "RetrievalRoleArn": "arn:aws:iam::111122223333:role/Example-App-Config-Role"
+ * }
+ * *\/
+ * // example id: to-create-a-configuration-profile-1632264580336
+ * ```
+ *
  */
 export class CreateConfigurationProfileCommand extends $Command<
   CreateConfigurationProfileCommandInput,

clients/client-appconfig/src/commands/CreateDeploymentStrategyCommand.ts

@@ -53,6 +53,31 @@ export interface CreateDeploymentStrategyCommandOutput extends DeploymentStrateg
  * @see {@link CreateDeploymentStrategyCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To create a deployment strategy
+ * ```javascript
+ * // The following create-deployment-strategy example creates a deployment strategy called Example-Deployment that takes 15 minutes and deploys the configuration to 25% of the application at a time. The strategy is also copied to an SSM Document.
+ * const input = {
+ *   "DeploymentDurationInMinutes": 15,
+ *   "GrowthFactor": 25,
+ *   "Name": "Example-Deployment",
+ *   "ReplicateTo": "SSM_DOCUMENT"
+ * };
+ * const command = new CreateDeploymentStrategyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "DeploymentDurationInMinutes": 15,
+ *   "FinalBakeTimeInMinutes": 0,
+ *   "GrowthFactor": 25,
+ *   "GrowthType": "LINEAR",
+ *   "Id": "1225qzk",
+ *   "Name": "Example-Deployment",
+ *   "ReplicateTo": "SSM_DOCUMENT"
+ * }
+ * *\/
+ * // example id: to-create-a-deployment-strategy-1632264783812
+ * ```
+ *
  */
 export class CreateDeploymentStrategyCommand extends $Command<
   CreateDeploymentStrategyCommandInput,

clients/client-appconfig/src/commands/CreateEnvironmentCommand.ts

@@ -57,6 +57,26 @@ export interface CreateEnvironmentCommandOutput extends Environment, __MetadataB
  * @see {@link CreateEnvironmentCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To create an environment
+ * ```javascript
+ * // The following create-environment example creates an AWS AppConfig environment named Example-Environment using the application you created using create-application
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "Name": "Example-Environment"
+ * };
+ * const command = new CreateEnvironmentCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ApplicationId": "339ohji",
+ *   "Id": "54j1r29",
+ *   "Name": "Example-Environment",
+ *   "State": "READY_FOR_DEPLOYMENT"
+ * }
+ * *\/
+ * // example id: to-create-an-environment-1632265124975
+ * ```
+ *
  */
 export class CreateEnvironmentCommand extends $Command<
   CreateEnvironmentCommandInput,

clients/client-appconfig/src/commands/CreateHostedConfigurationVersionCommand.ts

@@ -51,6 +51,29 @@ export interface CreateHostedConfigurationVersionCommandOutput extends HostedCon
  * @see {@link CreateHostedConfigurationVersionCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To create a hosted configuration version
+ * ```javascript
+ * // The following create-hosted-configuration-version example creates a new configuration in the AWS AppConfig configuration store.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "ConfigurationProfileId": "ur8hx2f",
+ *   "Content": "eyAiTmFtZSI6ICJFeGFtcGxlQXBwbGljYXRpb24iLCAiSWQiOiBFeGFtcGxlSUQsICJSYW5rIjogNyB9",
+ *   "ContentType": "text",
+ *   "LatestVersionNumber": 1
+ * };
+ * const command = new CreateHostedConfigurationVersionCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ApplicationId": "339ohji",
+ *   "ConfigurationProfileId": "ur8hx2f",
+ *   "ContentType": "text",
+ *   "VersionNumber": 1
+ * }
+ * *\/
+ * // example id: to-create-a-hosted-configuration-version-1632265196980
+ * ```
+ *
  */
 export class CreateHostedConfigurationVersionCommand extends $Command<
   CreateHostedConfigurationVersionCommandInput,

clients/client-appconfig/src/commands/DeleteApplicationCommand.ts

@@ -46,6 +46,18 @@ export interface DeleteApplicationCommandOutput extends __MetadataBearer {}
  * @see {@link DeleteApplicationCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To delete an application
+ * ```javascript
+ * // The following delete-application example deletes the specified application.
+ * //
+ * const input = {
+ *   "ApplicationId": "339ohji"
+ * };
+ * const command = new DeleteApplicationCommand(input);
+ * await client.send(command);
+ * // example id: to-delete-an-application-1632265343951
+ * ```
+ *
  */
 export class DeleteApplicationCommand extends $Command<
   DeleteApplicationCommandInput,

clients/client-appconfig/src/commands/DeleteConfigurationProfileCommand.ts

@@ -49,6 +49,18 @@ export interface DeleteConfigurationProfileCommandOutput extends __MetadataBeare
  * @see {@link DeleteConfigurationProfileCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To delete a configuration profile
+ * ```javascript
+ * // The following delete-configuration-profile example deletes the specified configuration profile.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "ConfigurationProfileId": "ur8hx2f"
+ * };
+ * const command = new DeleteConfigurationProfileCommand(input);
+ * await client.send(command);
+ * // example id: to-delete-a-configuration-profile-1632265401308
+ * ```
+ *
  */
 export class DeleteConfigurationProfileCommand extends $Command<
   DeleteConfigurationProfileCommandInput,

clients/client-appconfig/src/commands/DeleteDeploymentStrategyCommand.ts

@@ -46,6 +46,17 @@ export interface DeleteDeploymentStrategyCommandOutput extends __MetadataBearer
  * @see {@link DeleteDeploymentStrategyCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To delete a deployment strategy
+ * ```javascript
+ * // The following delete-deployment-strategy example deletes the specified deployment strategy.
+ * const input = {
+ *   "DeploymentStrategyId": "1225qzk"
+ * };
+ * const command = new DeleteDeploymentStrategyCommand(input);
+ * await client.send(command);
+ * // example id: to-delete-a-deployment-strategy-1632265473708
+ * ```
+ *
  */
 export class DeleteDeploymentStrategyCommand extends $Command<
   DeleteDeploymentStrategyCommandInput,

clients/client-appconfig/src/commands/DeleteEnvironmentCommand.ts

@@ -46,6 +46,18 @@ export interface DeleteEnvironmentCommandOutput extends __MetadataBearer {}
  * @see {@link DeleteEnvironmentCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To delete an environment
+ * ```javascript
+ * // The following delete-environment example deletes the specified application environment.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "EnvironmentId": "54j1r29"
+ * };
+ * const command = new DeleteEnvironmentCommand(input);
+ * await client.send(command);
+ * // example id: to-delete-an-environment-1632265641044
+ * ```
+ *
  */
 export class DeleteEnvironmentCommand extends $Command<
   DeleteEnvironmentCommandInput,

clients/client-appconfig/src/commands/DeleteHostedConfigurationVersionCommand.ts

@@ -49,6 +49,19 @@ export interface DeleteHostedConfigurationVersionCommandOutput extends __Metadat
  * @see {@link DeleteHostedConfigurationVersionCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To delete a hosted configuration version
+ * ```javascript
+ * // The following delete-hosted-configuration-version example deletes a configuration version hosted in the AWS AppConfig configuration store.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "ConfigurationProfileId": "ur8hx2f",
+ *   "VersionNumber": 1
+ * };
+ * const command = new DeleteHostedConfigurationVersionCommand(input);
+ * await client.send(command);
+ * // example id: to-delete-a-hosted-configuration-version-1632265720740
+ * ```
+ *
  */
 export class DeleteHostedConfigurationVersionCommand extends $Command<
   DeleteHostedConfigurationVersionCommandInput,

clients/client-appconfig/src/commands/GetApplicationCommand.ts

@@ -50,6 +50,23 @@ export interface GetApplicationCommandOutput extends Application, __MetadataBear
  * @see {@link GetApplicationCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To list details of an application
+ * ```javascript
+ * // The following get-application example lists the details of the specified application.
+ * const input = {
+ *   "ApplicationId": "339ohji"
+ * };
+ * const command = new GetApplicationCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "Id": "339ohji",
+ *   "Name": "example-application"
+ * }
+ * *\/
+ * // example id: to-list-details-of-an-application-1632265864702
+ * ```
+ *
  */
 export class GetApplicationCommand extends $Command<
   GetApplicationCommandInput,

clients/client-appconfig/src/commands/GetConfigurationCommand.ts

@@ -66,6 +66,26 @@ export interface GetConfigurationCommandOutput extends Configuration, __Metadata
  * @see {@link GetConfigurationCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To retrieve configuration details
+ * ```javascript
+ * // The following get-configuration example returns the configuration details of the example application. On subsequent calls to get-configuration, use the client-configuration-version parameter to only update the configuration of your application if the version has changed. Only updating the configuration when the version has changed avoids excess charges incurred by calling get-configuration.
+ * const input = {
+ *   "Application": "example-application",
+ *   "ClientId": "example-id",
+ *   "Configuration": "Example-Configuration-Profile",
+ *   "Environment": "Example-Environment"
+ * };
+ * const command = new GetConfigurationCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ConfigurationVersion": "1",
+ *   "ContentType": "application/octet-stream"
+ * }
+ * *\/
+ * // example id: to-retrieve-configuration-details-1632265954314
+ * ```
+ *
  */
 export class GetConfigurationCommand extends $Command<
   GetConfigurationCommandInput,

clients/client-appconfig/src/commands/GetConfigurationProfileCommand.ts

@@ -50,6 +50,27 @@ export interface GetConfigurationProfileCommandOutput extends ConfigurationProfi
  * @see {@link GetConfigurationProfileCommandOutput} for command's `response` shape.
  * @see {@link AppConfigClientResolvedConfig | config} for AppConfigClient's `config` shape.
  *
+ * @example To retrieve configuration profile details
+ * ```javascript
+ * // The following get-configuration-profile example returns the details of the specified configuration profile.
+ * const input = {
+ *   "ApplicationId": "339ohji",
+ *   "ConfigurationProfileId": "ur8hx2f"
+ * };
+ * const command = new GetConfigurationProfileCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ApplicationId": "339ohji",
+ *   "Id": "ur8hx2f",
+ *   "LocationUri": "ssm-parameter://Example-Parameter",
+ *   "Name": "Example-Configuration-Profile",
+ *   "RetrievalRoleArn": "arn:aws:iam::111122223333:role/Example-App-Config-Role"
+ * }
+ * *\/
+ * // example id: to-retrieve-configuration-profile-details-1632266081013
+ * ```
+ *
  */
 export class GetConfigurationProfileCommand extends $Command<
   GetConfigurationProfileCommandInput,