Merge pull request #826 from BitGo/DX-531

feat: add support for array examples with the @arrayExample tag

Author: anshchaturvedi

packages/openapi-generator/src/openapi.ts

@@ -7,6 +7,10 @@ import type { Route } from './route';
 import type { Schema } from './ir';
 import { Block } from 'comment-parser';
 
+type ExtendedOpenApiSchema = OpenAPIV3.SchemaObject & {
+  arrayExample?: string;
+};
+
 function schemaToOpenAPI(
   schema: Schema,
 ): OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined {
@@ -50,7 +54,14 @@ function schemaToOpenAPI(
         if (innerSchema === undefined) {
           return undefined;
         }
-        return { type: 'array', items: { ...innerSchema, ...defaultOpenAPIObject } };
+
+        const { arrayExample, ...rest } = defaultOpenAPIObject;
+
+        return {
+          type: 'array',
+          ...(arrayExample ? { example: JSON.parse(arrayExample) } : {}), // Add example to array if it exists
+          items: { ...innerSchema, ...rest },
+        };
       case 'object':
         return {
           type: 'object',
@@ -173,7 +184,7 @@ function schemaToOpenAPI(
     }
   };
 
-  function buildDefaultOpenAPIObject(schema: Schema): OpenAPIV3.SchemaObject {
+  function buildDefaultOpenAPIObject(schema: Schema): ExtendedOpenApiSchema {
     const emptyBlock: Block = { description: '', tags: [], source: [], problems: [] };
     const jsdoc = parseCommentBlock(schema.comment ?? emptyBlock);
 
@@ -196,6 +207,7 @@ function schemaToOpenAPI(
     const writeOnly = jsdoc?.tags?.writeOnly ?? schema.writeOnly;
     const format = jsdoc?.tags?.format ?? schema.format ?? schema.format;
     const title = jsdoc?.tags?.title ?? schema.title;
+    const arrayExample = jsdoc?.tags?.arrayExample ?? '';
 
     const deprecated =
       Object.keys(jsdoc?.tags || {}).includes('deprecated') || !!schema.deprecated;
@@ -223,7 +235,9 @@ function schemaToOpenAPI(
       ...(writeOnly ? { writeOnly: true } : {}),
       ...(format ? { format } : {}),
       ...(title ? { title } : {}),
+      ...(arrayExample ? { arrayExample } : {}),
     };
+
     return defaultOpenAPIObject;
   }
 

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

@@ -3567,3 +3567,112 @@ testCase("route with titles in request bodies", SCHEMA_WITH_TITLES_IN_REQUEST_BO
     }
   }
 });
+
+
+const ROUTE_WITH_ARRAY_EXAMPLE = `
+import * as t from 'io-ts';
+import * as h from '@api-ts/io-ts-http';
+
+export const route = h.httpRoute({
+  path: '/foo',
+  method: 'POST',
+  request: h.httpRequest({ 
+    params: {}, 
+    body: t.type({ 
+      /**
+       * @example "btc"
+       */
+      array1: t.array(t.string),
+      /**
+       * @example "btc" 
+       * @arrayExample ["btc", "eth"]
+       */
+      array2: t.array(t.string),
+      objectWithArray: t.type({
+        /**
+         * @arrayExample ["btc", "eth"]
+         */
+        nestedArray: t.array(t.string)
+      })
+    })
+  }),
+  response: {
+    200: t.literal('OK'),
+  },
+});`
+
+testCase("route with array examples", ROUTE_WITH_ARRAY_EXAMPLE,  {
+  openapi: '3.0.3',
+  info: {
+    title: 'Test',
+    version: '1.0.0'
+  },
+  paths: {
+    '/foo': {
+      post: {
+        parameters: [],
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  array1: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                      example: '"btc"'
+                    },
+                  },
+                  array2: {
+                    type: 'array',
+                    example: ['btc', 'eth'],
+                    items: {
+                      type: 'string',
+                      example: '"btc"'
+                    },
+                  },
+                  objectWithArray: {
+                    properties: {
+                      nestedArray: {
+                        example: [
+                          'btc',
+                          'eth'
+                        ],
+                        items: {
+                          type: 'string'
+                        },
+                        type: 'array'
+                      }
+                    },
+                    required: [
+                      'nestedArray'
+                    ],
+                    type: 'object'
+                  },   
+                },
+                required: [ 'array1', 'array2', 'objectWithArray' ],
+              },
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'OK',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'string',
+                  enum: [ 'OK' ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  components: {
+    schemas: {}
+  }
+});