Merge pull request #753 from BitGo/DX-338-@example-tag-in-generator

feat(openapi-generator): take and parse @example tags on JSDoc

Author: bitgopatmcl

packages/openapi-generator/src/jsdoc.ts

@@ -1,28 +1,53 @@
 import type { Block } from 'comment-parser';
 
+type Tags = Record<Exclude<string, 'example'>, string> & { example?: any };
+
 export type JSDoc = {
   summary?: string;
   description?: string;
-  tags?: Record<string, string>;
+  tags?: Tags;
 };
 
 export function parseCommentBlock(comment: Block): JSDoc {
   let summary: string = '';
   let description: string = '';
-  let tags: Record<string, string> = {};
+  let tags: Tags = {};
+  let writingExample = false;
 
   for (const line of comment.source) {
-    if (summary.length === 0) {
-      if (line.tokens.description === '') {
-        continue;
+    if (writingExample) {
+      tags['example'] = `${tags['example']}\n${line.source.split('*')[1]?.trim()}`;
+      try {
+        tags['example'] = JSON.parse(tags['example']);
+        writingExample = false;
+      } catch (e) {
+        if (line.source.endsWith('*/'))
+          throw new Error('@example contains invalid JSON');
+        else continue;
       }
-      summary = line.tokens.description;
     } else {
-      if (line.tokens.tag !== undefined && line.tokens.tag.length > 0) {
-        tags[line.tokens.tag.slice(1)] =
-          `${line.tokens.name} ${line.tokens.description}`.trim();
+      if (summary.length === 0) {
+        if (line.tokens.description === '') {
+          continue;
+        }
+        summary = line.tokens.description;
       } else {
-        description = `${description ?? ''}\n${line.tokens.description}`;
+        if (line.tokens.tag !== undefined && line.tokens.tag.length > 0) {
+          if (line.tokens.tag === '@example') {
+            tags['example'] = line.source.split('@example')[1]?.trim();
+            if (tags['example'].startsWith('{') || tags['example'].startsWith('[')) {
+              try {
+                tags['example'] = JSON.parse(tags['example']);
+              } catch (e) {
+                writingExample = true;
+              }
+            }
+          } else
+            tags[line.tokens.tag.slice(1)] =
+              `${line.tokens.name} ${line.tokens.description}`.trim();
+        } else {
+          description = `${description ?? ''}\n${line.tokens.description}`;
+        }
       }
     }
   }

packages/openapi-generator/src/openapi.ts

@@ -117,6 +117,7 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
   const tag = jsdoc.tags?.tag ?? '';
   const isInternal = jsdoc.tags?.private !== undefined;
   const isUnstable = jsdoc.tags?.unstable !== undefined;
+  const example = jsdoc.tags?.example;
 
   const requestBody =
     route.body === undefined
@@ -163,7 +164,10 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
           [Number(code)]: {
             description,
             content: {
-              'application/json': { schema: schemaToOpenAPI(response) },
+              'application/json': {
+                schema: schemaToOpenAPI(response),
+                ...(example !== undefined ? { example } : undefined),
+              },
             },
           },
         };

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

@@ -152,3 +152,173 @@ test('comment with a summary, description, and a tag in the middle of the descri
 
   assert.deepEqual(parseJSDoc(comment), expected);
 });
+
+test('parameter with a comment and an example string', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example foo
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    tags: {
+      example: 'foo',
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});
+
+test('parameter with a comment and an example object', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example { "test": "foo" }
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    // @ts-expect-error parser doesn't properly infer type
+    tags: {
+      example: { test: 'foo' },
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});
+
+test('parameter with a comment and an example object (multi-line)', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example {
+     *   "test": "foo"
+     * }
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    // @ts-expect-error parser doesn't properly infer type
+    tags: {
+      example: { test: 'foo' },
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});
+
+test('parameter with a comment and an example array', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example ["foo", "bar", "baz"]
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    // @ts-expect-error parser doesn't properly infer type
+    tags: {
+      example: ['foo', 'bar', 'baz'],
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});
+
+test('parameter with a comment and an invalid example object', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example { "test": "foo"
+     */
+  `;
+
+  assert.throws(() => parseJSDoc(comment), {
+    message: '@example contains invalid JSON',
+  });
+});
+
+test('parameter with a comment and an invalid example object (multi-line)', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example {
+     *   "test": "foo"
+     */
+  `;
+
+  assert.throws(() => parseJSDoc(comment), {
+    message: '@example contains invalid JSON',
+  });
+});
+
+test('parameter with a comment and an invalid example array', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example ["foo", "bar", "baz"
+     */
+  `;
+
+  assert.throws(() => parseJSDoc(comment), {
+    message: '@example contains invalid JSON',
+  });
+});
+
+test('parameter with a comment, an example object and a tag', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example { "test": "foo" }
+     * @tag api.example.test
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    // @ts-expect-error parser doesn't properly infer type
+    tags: {
+      example: { test: 'foo' },
+      tag: 'api.example.test',
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});
+
+test('parameter with a comment, an example object (multi-line) and a tag', () => {
+  const comment = `
+    /**
+     * A variable with example
+     * 
+     * @example {
+     *   "test": "foo"
+     * }
+     * @tag api.example.test
+     */
+  `;
+
+  const expected: JSDoc = {
+    summary: 'A variable with example',
+    // @ts-expect-error parser doesn't properly infer type
+    tags: {
+      example: { test: 'foo' },
+      tag: 'api.example.test',
+    },
+  };
+
+  assert.deepEqual(parseJSDoc(comment), expected);
+});