fix: handle type field called with 'enum' reserved word (#1983)

* fix: handle type field called with 'enum' reserved word

* chore: changeset

* chore: use node20 version of actions/upload-artifact

.changeset/selfish-experts-live.md

@@ -0,0 +1,6 @@
+---
+'@commercetools-docs/gatsby-theme-api-docs': patch
+'@commercetools-api-specs/test': patch
+---
+
+Correctly handle type field when the name is reserved word 'enum'

.github/workflows/main.yml

@@ -230,7 +230,7 @@ jobs:
           CYPRESS_CI: 'true'
 
       - name: Upload e2e artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v3-node20
         if: ${{ failure() }}
         with:
           name: self-learning-e2e-failure-snapshots-${{ github.run_attempt }}

api-specs/test/types/enums.raml

@@ -12,6 +12,16 @@ types:
       - EnumEntryOne
       - EnumEntryTwo
       - EnumEntryThree
+      - enum
+    (annotations.enumDescriptions):
+      EnumEntryOne: |
+        This is the first entry in the EnumTest enumeration.
+      EnumEntryTwo: |
+        This is the second entry in the EnumTest enumeration.
+      EnumEntryThree: |
+        This is the third entry in the EnumTest enumeration.
+      enum: |
+        This is an item called with a reserved word.
   EnumPropertiesType:
     description: Test data for properties with enums that are of differing primitive types
     properties:
@@ -99,4 +109,4 @@ types:
       enumValue9: Group 2
       enumValue10: Group 2
       enumWithoutDescription: Group 2
-      enumWithMarkdownDescription: Group 1
+      enumWithMarkdownDescription: Group 1

packages/gatsby-theme-api-docs/src/components/type/enum.js

@@ -4,6 +4,15 @@ import { Markdown } from '@commercetools-docs/ui-kit';
 import SpacingsStack from '@commercetools-uikit/spacings-stack';
 import { DescriptionText, DescriptionParagraph } from '../description';
 
+// @see https://github.com/commercetools/commercetools-docs-kit/blob/d55b7e3a263e918599bd2ac4a18830bd2f1c7d9b/packages/gatsby-transformer-raml/src/utils/type/do-recursion.mjs#L15
+// `enum` is converted to `enumeration` as it is a js reserved keyword. This must be taken into account when searching for the enum description.
+const enumDescriptionFinder = (enumDesc, value) => {
+  if (value === 'enum') {
+    return enumDesc.name === 'enumeration';
+  }
+  return enumDesc.name === value;
+};
+
 const Enum = ({
   values,
   enumDescriptions,
@@ -50,8 +59,8 @@ const Enum = ({
                           groupList[groupName].map((value) => {
                             const enumDescription =
                               enumDescriptions &&
-                              enumDescriptions.find(
-                                (enumDesc) => enumDesc.name === value
+                              enumDescriptions.find((enumDesc) =>
+                                enumDescriptionFinder(enumDesc, value)
                               );
                             return (
                               <React.Fragment key={value}>
@@ -95,7 +104,9 @@ const Enum = ({
             values.map((value) => {
               const enumDescription =
                 enumDescriptions &&
-                enumDescriptions.find((enumDesc) => enumDesc.name === value);
+                enumDescriptions.find((enumDesc) =>
+                  enumDescriptionFinder(enumDesc, value)
+                );
 
               return (
                 <React.Fragment key={value}>