Add support for union types in raml docs for api types (#2070)

* feat: support unions and multiply types for api-types * refactor: pre-processing of types and resources * refactor: apply suggested changes * chore: add changeset
commercetools · Sep 10, 2024 · 5f7ed85 · 5f7ed85
1 parent 61f888b
commit 5f7ed85
Show file tree

Hide file tree

Showing 15 changed files with 122 additions and 44 deletions.
diff --git a/.changeset/fluffy-parents-jog.md b/.changeset/fluffy-parents-jog.md
@@ -0,0 +1,6 @@
+---
+'@commercetools-docs/gatsby-transformer-raml': patch
+'@commercetools-docs/gatsby-theme-api-docs': patch
+---
+
+Display union references for api-types correctly.
diff --git a/api-specs/test/types/arrays.raml b/api-specs/test/types/arrays.raml
@@ -81,3 +81,15 @@ types:
         type: scalars.IntegerTestType[]
         uniqueItems: false
     example: !include ../examples/array-test-type.json
+  UnionReferenceTestType:
+    description: A test type with a reference with multiple type options.
+    type: object
+    properties:
+      reference:
+        type: ArrayTestType | WideLayoutArrayTestType
+        description: |
+          Reference description.
+      key?:
+        type: string
+        description: |
+          Key type description.
diff --git a/packages/gatsby-theme-api-docs/src/components/resource/method/parameters.js b/packages/gatsby-theme-api-docs/src/components/resource/method/parameters.js
@@ -21,7 +21,7 @@ const isRegex = (string) =>
   string.charAt(0) === '/' && string.charAt(string.length - 1) === '/';
 
 const isTypeUnion = (strType) => {
-  return typeof strType === 'string' && strType === 'Union';
+  return strType === 'Union';
 };
 
 const getParameterType = ({ name, unionParams }, type, apiKey) => {

diff --git a/packages/gatsby-theme-api-docs/src/components/type/properties/rows/name-type.js b/packages/gatsby-theme-api-docs/src/components/type/properties/rows/name-type.js
@@ -1,11 +1,12 @@
+import React from 'react';
 import PropTypes from 'prop-types';
 import styled from '@emotion/styled';
 import { designSystem, Markdown } from '@commercetools-docs/ui-kit';
 import SpacingsStack from '@commercetools-uikit/spacings-stack';
 import SpacingsInline from '@commercetools-uikit/spacings-inline';
 import { BetaTag } from '@commercetools-docs/gatsby-theme-docs';
 import { typography } from '../../../../design-system';
-import RegexProperty from '../../properties/regex-properties';
+import RegexProperty from '../regex-properties';
 import useTypesToRender from '../../../../hooks/use-type-to-render';
 import Required from '../../../required';
 
@@ -26,6 +27,42 @@ const BetaWrapper = styled.span`
   padding-top: 0.2rem;
 `;
 
+function UnionPropertiesRow(props) {
+  const typesToRender = useTypesToRender({
+    property: props.types,
+    apiKey: props.apiKey,
+    isParameter: true,
+  });
+
+  return (
+    <>
+      Can be{' '}
+      {typesToRender.map(({ type }, idx, { length }) =>
+        length > idx + 1 ? (
+          <span key={idx}>{type}, </span>
+        ) : (
+          <span key={idx}>or {type}</span>
+        )
+      )}
+    </>
+  );
+}
+
+UnionPropertiesRow.propTypes = {
+  apiKey: PropTypes.string.isRequired,
+  types: PropTypes.arrayOf({
+    name: PropTypes.string.isRequired,
+    type: PropTypes.string.isRequired,
+    required: PropTypes.bool,
+    description: PropTypes.string,
+    additionalDescription: PropTypes.string,
+    items: PropTypes.shape({
+      type: PropTypes.string,
+    }),
+  }).isRequired,
+};
+UnionPropertiesRow.displayName = 'UnionParametersRow';
+
 const NameType = (props) => {
   const typesToRender = useTypesToRender({
     property: props.property,
@@ -36,6 +73,20 @@ const NameType = (props) => {
   const isRegex = (string) =>
     string.charAt(0) === '/' && string.charAt(string.length - 1) === '/';
 
+  const isTypeUnion = (strType) => {
+    return strType === 'Union';
+  };
+
+  const getPropertiesType = ({ name, unionParams }, type, apiKey) => {
+    if (isRegex(name) && !typeToRender.displayPrefix) {
+      return `Any ${typeof type} parameter matching this regular expression`;
+    }
+    if (isTypeUnion(type)) {
+      return <UnionPropertiesRow types={unionParams} apiKey={apiKey} />;
+    }
+    return type;
+  };
+
   return (
     <SpacingsStack scale="xs">
       <PropertyName>
@@ -57,11 +108,7 @@ const NameType = (props) => {
       <PropertyType>
         {typeToRender.displayPrefix && typeToRender.displayPrefix}
 
-        {isRegex(props.property.name) && !typeToRender.displayPrefix
-          ? `Any ${typeof typeToRender.type} property matching this regular expression`
-          : typeof typeToRender.type === 'string'
-          ? typeToRender.type
-          : typeToRender.type}
+        {getPropertiesType(props.property, typeToRender.type, props.apiKey)}
         {'\u200B' /* zero-width space for the search crawler */}
       </PropertyType>
     </SpacingsStack>
@@ -76,6 +123,10 @@ NameType.propTypes = {
     items: PropTypes.shape({
       type: PropTypes.string.isRequired,
     }),
+    unionParams: PropTypes.shape({
+      type: PropTypes.string.isRequired,
+      builtinType: PropTypes.string.isRequired,
+    }),
     required: PropTypes.bool.isRequired,
     beta: PropTypes.bool,
   }).isRequired,

diff --git a/packages/gatsby-theme-api-docs/src/hooks/use-api-types.js b/packages/gatsby-theme-api-docs/src/hooks/use-api-types.js
@@ -48,6 +48,10 @@ export const useApiTypes = () => {
               items {
                 type
               }
+              unionParams {
+                builtinType
+                type
+              }
               maxItems
               maxLength
               maximum

diff --git a/packages/gatsby-theme-api-docs/src/hooks/use-type-to-render.js b/packages/gatsby-theme-api-docs/src/hooks/use-type-to-render.js
@@ -2,8 +2,8 @@ import { useTypeLocations } from './use-type-locations';
 import generateTypesToRender from '../utils/generate-type-to-render';
 
 /**
- * It accept either a single property or an array of properties.
- * The funtion returns an array of types to render
+ * It accepts either a single property or an array of properties.
+ * The function returns an array of types to render
  */
 function useTypesToRender({ property, apiKey, isParameter } = {}) {
   const typeLocations = useTypeLocations();

diff --git a/packages/gatsby-theme-api-docs/src/utils/extract-additional-info.js b/packages/gatsby-theme-api-docs/src/utils/extract-additional-info.js
@@ -16,6 +16,7 @@ const extractAdditionalInfo = (properties) => {
     'originalType',
     'required',
     'type',
+    'unionParams',
   ];
 
   mainInfo.forEach((field) => {

diff --git a/packages/gatsby-transformer-raml/src/create-api-node.mjs b/packages/gatsby-transformer-raml/src/create-api-node.mjs
@@ -1,6 +1,5 @@
-import doRecursion  from "./utils/api/do-recursion.mjs";
-import parametersToArray  from "./utils/parameters-to-array.mjs";
-
+import doRecursion from './utils/api/do-recursion.mjs';
+import propertiesToArray from './utils/properties-to-array.mjs';
 
 function createApiNode({
   apiKey,
@@ -34,7 +33,7 @@ function postProcessApi({ apiKey, api }) {
 
   postProcessedApi.apiKey = apiKey;
 
-  postProcessedApi.baseUriParameters = parametersToArray(
+  postProcessedApi.baseUriParameters = propertiesToArray(
     postProcessedApi.baseUriParameters
   );
 

diff --git a/packages/gatsby-transformer-raml/src/create-resource-node.mjs b/packages/gatsby-transformer-raml/src/create-resource-node.mjs
@@ -1,8 +1,6 @@
-import doRecursion  from "./utils/resource/do-recursion.mjs";
-import parametersToArray  from "./utils/parameters-to-array.mjs";
-import processMethods  from "./utils/resource/process-methods.mjs";
-
-
+import doRecursion from './utils/resource/do-recursion.mjs';
+import propertiesToArray from './utils/properties-to-array.mjs';
+import processMethods from './utils/resource/process-methods.mjs';
 
 function createResourceNode({
   apiKey,
@@ -50,11 +48,11 @@ function postProcessResource({
 
   postProcessedResource.apiKey = apiKey;
 
-  postProcessedResource.uriParameters = parametersToArray(
+  postProcessedResource.uriParameters = propertiesToArray(
     postProcessedResource.uriParameters
   );
 
-  postProcessedResource.baseUriParameters = parametersToArray(
+  postProcessedResource.baseUriParameters = propertiesToArray(
     postProcessedResource.baseUriParameters
   );
 

diff --git a/packages/gatsby-transformer-raml/src/create-type-node.mjs b/packages/gatsby-transformer-raml/src/create-type-node.mjs
@@ -4,6 +4,7 @@ import resolveConflictingFieldTypes from './utils/type/resolve-conflicting-field
 import generateType from './utils/type/generate-type.mjs';
 import generateBuiltinType from './utils/type/generate-built-in-type.mjs';
 import { examplesToArray } from './utils/resource/examples-to-array.mjs';
+import propertiesToArray from './utils/properties-to-array.mjs';
 
 function createTypeNode({
   apiKey,
@@ -74,7 +75,7 @@ function processProperties({
   let propertiesArray;
 
   if (properties) {
-    propertiesArray = propertiesToArrays(properties);
+    propertiesArray = propertiesToArray(properties);
     propertiesArray = propertiesArray.filter(
       (property) => !property.deprecated && !property.markDeprecated
     );
@@ -100,12 +101,6 @@ function processProperties({
   return undefined;
 }
 
-function propertiesToArrays(properties) {
-  return Object.entries(properties).map(([key, value]) => {
-    return { ...value, name: key };
-  });
-}
-
 function enumValuesToArray(enumValue) {
   if (enumValue) {
     return Object.entries(enumValue).map(([key, value]) => {

diff --git a/packages/gatsby-transformer-raml/src/schema/define-raml-type.mjs b/packages/gatsby-transformer-raml/src/schema/define-raml-type.mjs
@@ -70,9 +70,17 @@ const defineRamlType = ({ schema, createTypes }) => {
         pattern: 'String',
         required: 'Boolean!',
         type: 'String!',
+        unionParams: '[RamlTypePropertyUnionParameter!]',
         uniqueItems: 'Boolean',
       },
     }),
+    schema.buildObjectType({
+      name: 'RamlTypePropertyUnionParameter',
+      fields: {
+        type: 'String!',
+        builtinType: 'String!',
+      },
+    }),
   ];
   createTypes(typeDefs);
 };

diff --git a/...er-raml/src/utils/parameters-to-array.mjs → ...er-raml/src/utils/properties-to-array.mjs b/...er-raml/src/utils/parameters-to-array.mjs → ...er-raml/src/utils/properties-to-array.mjs
@@ -9,9 +9,9 @@ function getTypes(typeUnion) {
   return results;
 }
 
-function parametersToArray(parameters) {
-  if (parameters) {
-    return Object.entries(parameters).map(([key, parameter]) => {
+function propertiesToArray(properties) {
+  if (properties) {
+    return Object.entries(properties).map(([key, parameter]) => {
       const paramType = generateType(parameter);
       const isUnionType = paramType === 'Union';
       return {
@@ -27,4 +27,4 @@ function parametersToArray(parameters) {
   return undefined;
 }
 
-export default parametersToArray;
+export default propertiesToArray;
diff --git a/...aml/src/utils/parameters-to-array.spec.js → ...aml/src/utils/properties-to-array.spec.js b/...aml/src/utils/parameters-to-array.spec.js → ...aml/src/utils/properties-to-array.spec.js
@@ -1,8 +1,8 @@
-import parametersToArray from './parameters-to-array.mjs';
+import propertiesToArray from './properties-to-array.mjs';
 
-describe('parameters-to-array.js', () => {
+describe('properties-to-array.js', () => {
   it('should transform objects of query parameters to array', () => {
-    const parametersBefore = {
+    const propertiesBefore = {
       where: {
         required: false,
         type: 'string',
@@ -16,7 +16,7 @@ describe('parameters-to-array.js', () => {
       },
     };
 
-    const parametersAfter = [
+    const propertiesAfter = [
       {
         name: 'where',
         required: false,
@@ -33,11 +33,11 @@ describe('parameters-to-array.js', () => {
       },
     ];
 
-    expect(parametersToArray(parametersBefore)).toEqual(parametersAfter);
+    expect(propertiesToArray(propertiesBefore)).toEqual(propertiesAfter);
   });
 
   it('should transform number to float', () => {
-    const parametersBefore = {
+    const propertiesBefore = {
       limit: {
         required: false,
         type: 'integer',
@@ -51,7 +51,7 @@ describe('parameters-to-array.js', () => {
       },
     };
 
-    const parametersAfter = [
+    const propertiesAfter = [
       {
         name: 'limit',
         required: false,
@@ -68,19 +68,19 @@ describe('parameters-to-array.js', () => {
       },
     ];
 
-    expect(parametersToArray(parametersBefore)).toEqual(parametersAfter);
+    expect(propertiesToArray(propertiesBefore)).toEqual(propertiesAfter);
   });
 
   it('should properly convert union types transform number to float', () => {
-    const parametersBefore = {
+    const propertiesBefore = {
       unionParameter: {
         required: false,
         type: 'integer | string | number',
         builtinType: 'Union',
       },
     };
 
-    const parametersAfter = [
+    const propertiesAfter = [
       {
         name: 'unionParameter',
         required: false,
@@ -94,6 +94,6 @@ describe('parameters-to-array.js', () => {
       },
     ];
 
-    expect(parametersToArray(parametersBefore)).toEqual(parametersAfter);
+    expect(propertiesToArray(propertiesBefore)).toEqual(propertiesAfter);
   });
 });
diff --git a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs
@@ -1,4 +1,4 @@
-import parametersToArray from '../parameters-to-array.mjs';
+import propertiesToArray from '../properties-to-array.mjs';
 import responsesToArray from './responses-to-array.mjs';
 import headersToArray from './headers-to-array.mjs';
 import codeExamplesToArray from './code-examples-to-array.mjs';
@@ -16,7 +16,7 @@ function processMethods({
 
   methods.forEach((method) => {
     if (returnedMethods[method]) {
-      returnedMethods[method].queryParameters = parametersToArray(
+      returnedMethods[method].queryParameters = propertiesToArray(
         returnedMethods[method].queryParameters
       );
 

diff --git a/websites/api-docs-smoke-test/src/content/types/general.mdx b/websites/api-docs-smoke-test/src/content/types/general.mdx
@@ -21,6 +21,10 @@ import { ApiType } from "/shortcodes"
 
 <ApiType apiKey="test" type="ArrayTestType" />
 
+# UnionReferenceTestType
+
+<ApiType apiKey="test" type="UnionReferenceTestType" />
+
 # DateTestType
 
 <ApiType apiKey="test" type="DateTestType" />