fix(core): add x-enum-descriptions support (#2072)

Co-authored-by: Sil <[email protected]>

Author: Sil1g

packages/core/src/generators/schema-definition.ts

@@ -1,6 +1,11 @@
 import isEmpty from 'lodash.isempty';
 import type { SchemaObject, SchemasObject } from 'openapi3-ts/oas30';
-import { getEnum, getEnumNames, resolveDiscriminators } from '../getters';
+import {
+  getEnum,
+  getEnumDescriptions,
+  getEnumNames,
+  resolveDiscriminators,
+} from '../getters';
 import { resolveRef, resolveValue } from '../resolvers';
 import type {
   ContextSpecs,
@@ -86,6 +91,7 @@ export const generateSchemasDefinition = (
           schemaName,
           getEnumNames(resolvedValue.originalSchema),
           context.output.override.enumGenerationType,
+          getEnumDescriptions(resolvedValue.originalSchema),
         );
       } else if (schemaName === resolvedValue.value && resolvedValue.isRef) {
         // Don't add type if schema has same name and the referred schema will be an interface

packages/core/src/getters/combine.ts

@@ -8,7 +8,11 @@ import {
   SchemaType,
 } from '../types';
 import { getNumberWord, pascal, isSchema } from '../utils';
-import { getEnumImplementation, getEnumNames } from './enum';
+import {
+  getEnumDescriptions,
+  getEnumImplementation,
+  getEnumNames,
+} from './enum';
 import { getScalar } from './scalar';
 import uniq from 'lodash.uniq';
 
@@ -283,8 +287,9 @@ const getCombineEnumValue = ({
       }
 
       const names = getEnumNames(originalSchema[i]);
+      const descriptions = getEnumDescriptions(originalSchema[i]);
 
-      return getEnumImplementation(e, names);
+      return getEnumImplementation(e, names, descriptions);
     })
     .join('');
 

packages/core/src/getters/enum.ts

@@ -11,14 +11,23 @@ export const getEnumNames = (schemaObject: SchemaObject | undefined) => {
   );
 };
 
+export const getEnumDescriptions = (schemaObject: SchemaObject | undefined) => {
+  return (
+    schemaObject?.['x-enumDescriptions'] ||
+    schemaObject?.['x-enumdescriptions'] ||
+    schemaObject?.['x-enum-descriptions']
+  );
+};
+
 export const getEnum = (
   value: string,
   enumName: string,
   names: string[] | undefined,
   enumGenerationType: EnumGeneration,
+  descriptions?: string[],
 ) => {
   if (enumGenerationType === EnumGeneration.CONST)
-    return getTypeConstEnum(value, enumName, names);
+    return getTypeConstEnum(value, enumName, names, descriptions);
   if (enumGenerationType === EnumGeneration.ENUM)
     return getNativeEnum(value, enumName, names);
   if (enumGenerationType === EnumGeneration.UNION)
@@ -30,6 +39,7 @@ const getTypeConstEnum = (
   value: string,
   enumName: string,
   names?: string[],
+  descriptions?: string[],
 ) => {
   let enumValue = `export type ${enumName} = typeof ${enumName}[keyof typeof ${enumName}]`;
 
@@ -40,9 +50,9 @@ const getTypeConstEnum = (
 
   enumValue += ';\n';
 
-  const implementation = getEnumImplementation(value, names);
+  const implementation = getEnumImplementation(value, names, descriptions);
 
-  enumValue += `\n\n`;
+  enumValue += '\n\n';
 
   enumValue += '// eslint-disable-next-line @typescript-eslint/no-redeclare\n';
 
@@ -51,15 +61,23 @@ const getTypeConstEnum = (
   return enumValue;
 };
 
-export const getEnumImplementation = (value: string, names?: string[]) => {
+export const getEnumImplementation = (
+  value: string,
+  names?: string[],
+  descriptions?: string[],
+) => {
   // empty enum or null-only enum
   if (value === '') return '';
 
   return [...new Set(value.split(' | '))].reduce((acc, val, index) => {
     const name = names?.[index];
+    const description = descriptions?.[index];
+    const comment = description ? `  /** ${description} */\n` : '';
+
     if (name) {
       return (
         acc +
+        comment +
         `  ${keyword.isIdentifierNameES5(name) ? name : `'${name}'`}: ${val},\n`
       );
     }
@@ -83,6 +101,7 @@ export const getEnumImplementation = (value: string, names?: string[]) => {
 
     return (
       acc +
+      comment +
       `  ${keyword.isIdentifierNameES5(key) ? key : `'${key}'`}: ${val},\n`
     );
   }, '');

packages/core/src/getters/query-params.ts

@@ -8,7 +8,7 @@ import {
   GetterQueryParam,
 } from '../types';
 import { jsDoc, pascal, sanitize } from '../utils';
-import { getEnum, getEnumNames } from './enum';
+import { getEnum, getEnumDescriptions, getEnumNames } from './enum';
 import { getKey } from './keys';
 
 type QueryParamsType = {
@@ -73,6 +73,7 @@ const getQueryParamsTypes = (
         enumName,
         getEnumNames(resolvedValue.originalSchema),
         context.output.override.enumGenerationType,
+        getEnumDescriptions(resolvedValue.originalSchema),
       );
 
       return {

packages/core/src/resolvers/object.ts

@@ -1,5 +1,5 @@
 import { ReferenceObject, SchemaObject } from 'openapi3-ts/oas30';
-import { getEnum, getEnumNames } from '../getters/enum';
+import { getEnum, getEnumDescriptions, getEnumNames } from '../getters/enum';
 import { ContextSpecs, ResolverValue } from '../types';
 import { jsDoc } from '../utils';
 import { resolveValue } from './value';
@@ -66,6 +66,7 @@ const resolveObjectOriginal = ({
       propName,
       getEnumNames(resolvedValue.originalSchema),
       context.output.override.enumGenerationType,
+      getEnumDescriptions(resolvedValue.originalSchema),
     );
 
     return {

tests/specifications/enums.yaml

@@ -92,6 +92,11 @@ components:
               - Brown
               - White
               - Grey
+            x-enum-descriptions:
+              - Represents black colour
+              - Represents brown colour
+              - Represents white colour
+              - Represents grey colour
             enum:
               - BLACK
               - BROWN