Merge pull request #861 from BitGo/DX-644

feat: consolidate unknown unions with well defined codecs

Author: ad-world

packages/openapi-generator/src/openapi.ts

@@ -102,6 +102,10 @@ export function schemaToOpenAPI(
         const nonUndefinedSchema = schema.schemas.find((s) => s.type !== 'undefined');
         // If nullSchema exists, that means that the union is also nullable
         const nullSchema = schema.schemas.find((s) => s.type === 'null');
+
+        // If any schema exists and it is in union with another schema - we can remove the any schema as an optimization
+        const unknownSchema = schema.schemas.find((s) => s.type === 'any');
+
         // and we can just return the other schema (while attaching the comment to that schema)
         const isOptional =
           schema.schemas.length >= 2 && undefinedSchema && nonUndefinedSchema;
@@ -113,6 +117,29 @@ export function schemaToOpenAPI(
           });
         }
 
+        // This is an edge case for something like this -> t.union([WellDefinedCodec, t.unknown])
+        // It doesn't make sense to display the unknown codec in the OpenAPI spec so this essentially strips it out of the generation
+        // so that we don't present useless information to the user
+        const isUnionWithUnknown = schema.schemas.length >= 2 && unknownSchema;
+        if (isUnionWithUnknown) {
+          const nonUnknownSchemas = schema.schemas.filter((s) => s.type !== 'any');
+
+          if (nonUnknownSchemas.length === 1 && nonUnknownSchemas[0] !== undefined) {
+            return schemaToOpenAPI({
+              ...nonUnknownSchemas[0],
+              comment: schema.comment,
+              ...(nullSchema ? { nullable: true } : {}),
+            });
+          } else if (nonUnknownSchemas.length > 1) {
+            return schemaToOpenAPI({
+              type: 'union',
+              schemas: nonUnknownSchemas,
+              comment: schema.comment,
+              ...(nullSchema ? { nullable: true } : {}),
+            });
+          }
+        }
+
         for (const s of schema.schemas) {
           if (s.type === 'null') {
             nullable = true;

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

@@ -4602,3 +4602,101 @@ testCase("route with record types", ROUTE_WITH_RECORD_TYPES, {
   }
 });
 
+const ROUTE_WITH_UNKNOWN_UNIONS = `
+import * as t from 'io-ts';
+import * as h from '@api-ts/io-ts-http';
+
+const UnknownUnion = t.union([t.string, t.number, t.boolean, t.unknown]);
+const SingleUnknownUnion = t.union([t.unknown, t.string]);
+
+const NestedUnknownUnion = t.union([t.union([t.string, t.unknown]), t.union([t.boolean, t.unknown])]);
+
+export const route = h.httpRoute({
+  path: '/foo',
+  method: 'GET',
+  request: h.httpRequest({}),
+  response: {
+    200: {
+      single: SingleUnknownUnion,
+      unknown: UnknownUnion,
+      nested: NestedUnknownUnion,
+    }
+  },
+});
+`;
+
+testCase("route with unknown unions", ROUTE_WITH_UNKNOWN_UNIONS, {
+  info: {
+    title: 'Test',
+    version: '1.0.0'
+  },
+  openapi: '3.0.3',
+  paths: {
+    '/foo': {
+      get: {
+        parameters: [],
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                schema: {
+                  properties: {
+                    nested: {
+                      '$ref': '#/components/schemas/NestedUnknownUnion'
+                    },
+                    single: {
+                      '$ref': '#/components/schemas/SingleUnknownUnion'
+                    },
+                    unknown: {
+                      '$ref': '#/components/schemas/UnknownUnion'
+                    }
+                  },
+                  required: [
+                    'single',
+                    'unknown',
+                    'nested'
+                  ],
+                  type: 'object'
+                }
+              }
+            },
+            description: 'OK'
+          }
+        }
+      }
+    }
+  },
+  components: {
+    schemas: {
+      NestedUnknownUnion: {
+        oneOf: [
+          {
+            type: 'string'
+          },
+          {
+            type: 'boolean'
+          }
+        ],
+        title: 'NestedUnknownUnion'
+      },
+      SingleUnknownUnion: {
+        title: 'SingleUnknownUnion',
+        type: 'string'
+      },
+      UnknownUnion: {
+        oneOf: [
+          {
+            type: 'string'
+          },
+          {
+            type: 'number'
+          },
+          {
+            type: 'boolean'
+          }
+        ],
+        title: 'UnknownUnion'
+      }
+    }
+  },
+});