Merge pull request #776 from BitGo/DX-434-fix-description-outputs

feat: add support for `descriptions` in OpenAPI specs

Author: bitgopatmcl

packages/openapi-generator/src/openapi.ts

@@ -50,6 +50,7 @@ function schemaToOpenAPI(
       case 'object':
         return {
           type: 'object',
+          ...defaultObject,
           properties: Object.entries(schema.properties).reduce(
             (acc, [name, prop]) => {
               const innerSchema = schemaToOpenAPI(prop);
@@ -72,6 +73,7 @@ function schemaToOpenAPI(
             }
             return [innerSchema];
           }),
+          ...defaultObject,
         };
       case 'union':
         let nullable = false;
@@ -95,10 +97,15 @@ function schemaToOpenAPI(
             )[0] === '$ref'
           )
             // OpenAPI spec doesn't allow $ref properties to have siblings, so they're wrapped in an 'allOf' array
-            return { ...(nullable ? { nullable } : {}), allOf: oneOf };
-          else return { ...(nullable ? { nullable } : {}), ...oneOf[0] };
+            return {
+              ...(nullable ? { nullable } : {}),
+              allOf: oneOf,
+              ...defaultObject,
+            };
+          else
+            return { ...(nullable ? { nullable } : {}), ...oneOf[0], ...defaultObject };
         } else {
-          return { ...(nullable ? { nullable } : {}), oneOf };
+          return { ...(nullable ? { nullable } : {}), oneOf, ...defaultObject };
         }
       case 'record':
         const additionalProperties = schemaToOpenAPI(schema.codomain);
@@ -108,6 +115,7 @@ function schemaToOpenAPI(
         return {
           type: 'object',
           additionalProperties,
+          ...defaultObject,
         };
       case 'undefined':
         return undefined;

packages/openapi-generator/src/optimize.ts

@@ -106,7 +106,13 @@ export function optimize(schema: Schema): Schema {
         continue;
       }
       const [isOptional, filteredSchema] = filterUndefinedUnion(optimized);
+
+      if (prop.comment) {
+        filteredSchema.comment = prop.comment;
+      }
+
       properties[key] = filteredSchema;
+
       if (schema.required.indexOf(key) >= 0 && !isOptional) {
         required.push(key);
       }
@@ -123,11 +129,26 @@ export function optimize(schema: Schema): Schema {
   } else if (schema.type === 'intersection') {
     return foldIntersection(schema, optimize);
   } else if (schema.type === 'union') {
-    return simplifyUnion(schema, optimize);
+    const simplified = simplifyUnion(schema, optimize);
+    if (schema.comment) {
+      return { ...simplified, comment: schema.comment };
+    }
+
+    return simplified;
   } else if (schema.type === 'array') {
     const optimized = optimize(schema.items);
+    if (schema.comment) {
+      return { type: 'array', items: optimized, comment: schema.comment };
+    }
     return { type: 'array', items: optimized };
   } else if (schema.type === 'record') {
+    if (schema.comment) {
+      return {
+        type: 'record',
+        codomain: optimize(schema.codomain),
+        comment: schema.comment,
+      };
+    }
     return { type: 'record', codomain: optimize(schema.codomain) };
   } else if (schema.type === 'tuple') {
     const schemas = schema.schemas.map(optimize);