feat: require @description tags for enum comments

Author: koralkulacoglu

packages/openapi-generator/src/knownImports.ts

@@ -2,6 +2,7 @@ import * as E from 'fp-ts/Either';
 
 import { isPrimitive, type Schema } from './ir';
 import { errorLeft } from './error';
+import { parseCommentBlock } from './jsdoc';
 
 export type DerefFn = (ref: Schema) => E.Either<string, Schema>;
 export type KnownCodec = (
@@ -132,9 +133,12 @@ export const KNOWN_IMPORTS: KnownImports = {
 
       for (const prop of enumValues) {
         const propertySchema = arg.properties[prop];
-        if (propertySchema?.comment?.description) {
-          enumDescriptions[prop] = propertySchema.comment.description;
-          hasDescriptions = true;
+        if (propertySchema?.comment) {
+          const jsdoc = parseCommentBlock(propertySchema.comment);
+          if (jsdoc.tags?.description) {
+            enumDescriptions[prop] = jsdoc.tags.description;
+            hasDescriptions = true;
+          }
         }
       }
 

packages/openapi-generator/test/openapi/comments.test.ts

@@ -1450,17 +1450,29 @@ import * as h from '@api-ts/io-ts-http';
  */
 export const TransactionRequestState = t.keyof(
   {
-    /** Transaction is waiting for approval from authorized users */
+    /** 
+     * @description Transaction is waiting for approval from authorized users 
+     */
     pendingApproval: 1,
-    /** Transaction was canceled by the user */
+    /** 
+     * @description Transaction was canceled by the user 
+     */
     canceled: 1,
-    /** Transaction was rejected by approvers */
+    /** 
+     * @description Transaction was rejected by approvers 
+     */
     rejected: 1,
-    /** Transaction has been initialized but not yet processed */
+    /** 
+     * @description Transaction has been initialized but not yet processed 
+     */
     initialized: 1,
-    /** Transaction is ready to be delivered */
+    /** 
+     * @description Transaction is ready to be delivered 
+     */
     pendingDelivery: 1,
-    /** Transaction has been successfully delivered */
+    /** 
+     * @description Transaction has been successfully delivered 
+     */
     delivered: 1,
   },
   'TransactionRequestState',
@@ -1683,6 +1695,105 @@ testCase(
   },
 );
 
+const ROUTE_WITH_ENUM_COMMENTS_WITHOUT_DESCRIPTION_TAG = `
+import * as t from 'io-ts';
+import * as h from '@api-ts/io-ts-http';
+
+/**
+ * Enum with comments but no @description tags
+ */
+export const StatusWithComments = t.keyof(
+  {
+    /** processing = a case has been picked up by the Trust Committee Email Worker, and is being...processed */
+    processing: 1,
+    /** approved status */
+    approved: 1,
+    denied: 1,
+  },
+  'StatusWithComments',
+);
+
+/**
+ * Route to test enum with comments but no @description tags
+ *
+ * @operationId api.v1.enumCommentsWithoutDescription
+ * @tag Test Routes
+ */
+export const route = h.httpRoute({
+  path: '/status-comments',
+  method: 'GET',
+  request: h.httpRequest({
+    query: {
+      status: StatusWithComments,
+    },
+  }),
+  response: {
+    200: {
+      result: t.string
+    }
+  },
+});
+`;
+
+testCase(
+  'enum with comments but no @description tags should not use x-enumDescriptions',
+  ROUTE_WITH_ENUM_COMMENTS_WITHOUT_DESCRIPTION_TAG,
+  {
+    openapi: '3.0.3',
+    info: {
+      title: 'Test',
+      version: '1.0.0',
+    },
+    paths: {
+      '/status-comments': {
+        get: {
+          summary: 'Route to test enum with comments but no @description tags',
+          operationId: 'api.v1.enumCommentsWithoutDescription',
+          tags: ['Test Routes'],
+          parameters: [
+            {
+              name: 'status',
+              in: 'query',
+              required: true,
+              schema: {
+                $ref: '#/components/schemas/StatusWithComments',
+              },
+            },
+          ],
+          responses: {
+            200: {
+              description: 'OK',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      result: {
+                        type: 'string',
+                      },
+                    },
+                    required: ['result'],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        StatusWithComments: {
+          title: 'StatusWithComments',
+          type: 'string',
+          enum: ['processing', 'approved', 'denied'],
+          description: 'Enum with comments but no @description tags',
+        },
+      },
+    },
+  },
+);
+
 const ROUTE_WITH_MARKDOWN_LIST = `
 import * as t from 'io-ts';
 import * as h from '@api-ts/io-ts-http';