docs(core): fix CfnMapping example (#16882)

The CloudFormation intrinsic function `Fn::FindInMap` only supports alphanumeric characters as name. However, the `CfnMapping` examples in the README file contain hyphens in the name field. This causes an error when the code is deployed. I changed the structure of the examples to create examples that can be deployed in AWS. Fixes #16866. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
aws · Oct 22, 2021 · 54ca910 · 54ca910
1 parent 09b02f0
commit 54ca910
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 30 deletions.
diff --git a/packages/@aws-cdk/core/README.md b/packages/@aws-cdk/core/README.md
@@ -753,26 +753,30 @@ CloudFormation [mappings][cfn-mappings] are created and queried using the
 ```ts
 const regionTable = new CfnMapping(this, 'RegionTable', {
   mapping: {
-    regionName: {
-      'us-east-1': 'US East (N. Virginia)',
-      'us-east-2': 'US East (Ohio)',
+    'us-east-1': {
+      regionName: 'US East (N. Virginia)',
+      // ...
+    },
+    'us-east-2': {
+      regionName: 'US East (Ohio)',
       // ...
     },
     // ...
   }
 });
 
-regionTable.findInMap('regionName', Aws.REGION);
+regionTable.findInMap(Aws.REGION, 'regionName')
 ```
 
 This will yield the following template:
 
 ```yaml
 Mappings:
   RegionTable:
-    regionName:
-      us-east-1: US East (N. Virginia)
-      us-east-2: US East (Ohio)
+    us-east-1:
+      regionName: US East (N. Virginia)
+    us-east-2:
+      regionName: US East (Ohio)
 ```
 
 Mappings can also be synthesized "lazily"; lazy mappings will only render a "Mappings"
@@ -787,24 +791,25 @@ call to `findInMap` will be able to resolve the value during synthesis and simpl
 ```ts
 const regionTable = new CfnMapping(this, 'RegionTable', {
   mapping: {
-    regionName: {
-      'us-east-1': 'US East (N. Virginia)',
-      'us-east-2': 'US East (Ohio)',
+    'us-east-1': {
+      regionName: 'US East (N. Virginia)',
+    },
+    'us-east-2': {
+      regionName: 'US East (Ohio)',
     },
   },
   lazy: true,
 });
 
-regionTable.findInMap('regionName', 'us-east-2');
+regionTable.findInMap('us-east-2', 'regionName');
 ```
 
 On the other hand, the following code will produce the "Mappings" section shown above,
-since the second-level key is an unresolved token. The call to `findInMap` will return a
-token that resolves to `{ Fn::FindInMap: [ 'RegionTable', 'regionName', { Ref: AWS::Region
-} ] }`.
+since the top-level key is an unresolved token. The call to `findInMap` will return a token that resolves to 
+`{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`.
 
 ```ts
-regionTable.findInMap('regionName', Aws.REGION);
+regionTable.findInMap(Aws.REGION, 'regionName');
 ```
 
 [cfn-mappings]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html

diff --git a/packages/aws-cdk-lib/README.md b/packages/aws-cdk-lib/README.md
@@ -786,26 +786,30 @@ CloudFormation [mappings][cfn-mappings] are created and queried using the
 ```ts
 const regionTable = new CfnMapping(this, 'RegionTable', {
   mapping: {
-    regionName: {
-      'us-east-1': 'US East (N. Virginia)',
-      'us-east-2': 'US East (Ohio)',
+    'us-east-1': {
+      regionName: 'US East (N. Virginia)',
+      // ...
+    },
+    'us-east-2': {
+      regionName: 'US East (Ohio)',
       // ...
     },
     // ...
   }
 });
 
-regionTable.findInMap('regionName', Aws.REGION);
+regionTable.findInMap(Aws.REGION, 'regionName')
 ```
 
 This will yield the following template:
 
 ```yaml
 Mappings:
   RegionTable:
-    regionName:
-      us-east-1: US East (N. Virginia)
-      us-east-2: US East (Ohio)
+    us-east-1:
+      regionName: US East (N. Virginia)
+    us-east-2:
+      regionName: US East (Ohio)
 ```
 
 Mappings can also be synthesized "lazily"; lazy mappings will only render a "Mappings"
@@ -820,24 +824,25 @@ call to `findInMap` will be able to resolve the value during synthesis and simpl
 ```ts
 const regionTable = new CfnMapping(this, 'RegionTable', {
   mapping: {
-    regionName: {
-      'us-east-1': 'US East (N. Virginia)',
-      'us-east-2': 'US East (Ohio)',
+    'us-east-1': {
+      regionName: 'US East (N. Virginia)',
+    },
+    'us-east-2': {
+      regionName: 'US East (Ohio)',
     },
   },
   lazy: true,
 });
 
-regionTable.findInMap('regionName', 'us-east-2');
+regionTable.findInMap('us-east-2', 'regionName');
 ```
 
 On the other hand, the following code will produce the "Mappings" section shown above,
-since the second-level key is an unresolved token. The call to `findInMap` will return a
-token that resolves to `{ Fn::FindInMap: [ 'RegionTable', 'regionName', { Ref: AWS::Region
-} ] }`.
+since the top-level key is an unresolved token. The call to `findInMap` will return a token that resolves to 
+`{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`.
 
 ```ts
-regionTable.findInMap('regionName', Aws.REGION);
+regionTable.findInMap(Aws.REGION, 'regionName');
 ```
 
 [cfn-mappings]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html