feat(openapi-generator): add support for inline type descriptions

DX-427

Author: ad-world

packages/openapi-generator/src/openapi.ts

@@ -14,13 +14,27 @@ function schemaToOpenAPI(
   const createOpenAPIObject = (
     schema: Schema,
   ): OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined => {
+    const description = schema.comment?.description;
+
+    const defaultObject = {
+      ...(description ? { description } : {}),
+    };
+
     switch (schema.type) {
       case 'boolean':
       case 'string':
       case 'number':
-        return { type: schema.type, ...(schema.enum ? { enum: schema.enum } : {}) };
+        return {
+          type: schema.type,
+          ...(schema.enum ? { enum: schema.enum } : {}),
+          ...defaultObject,
+        };
       case 'integer':
-        return { type: 'number', ...(schema.enum ? { enum: schema.enum } : {}) };
+        return {
+          type: 'number',
+          ...(schema.enum ? { enum: schema.enum } : {}),
+          ...defaultObject,
+        };
       case 'null':
         // TODO: OpenAPI v3 does not have an explicit null type, is there a better way to represent this?
         // Or should we just conflate explicit null and undefined properties?
@@ -32,7 +46,7 @@ function schemaToOpenAPI(
         if (innerSchema === undefined) {
           return undefined;
         }
-        return { type: 'array', items: innerSchema };
+        return { type: 'array', items: innerSchema, ...defaultObject };
       case 'object':
         return {
           type: 'object',
@@ -146,13 +160,25 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
     {},
   );
 
+  const stripTopLevelComment = (schema: Schema) => {
+    const copy = { ...schema };
+
+    if (copy.comment?.description !== undefined && copy.comment?.description !== '') {
+      copy.comment.description = '';
+    }
+
+    return copy;
+  };
+
+  const topLevelStripped = stripTopLevelComment(route.body!);
+
   const requestBody =
     route.body === undefined
       ? {}
       : {
           requestBody: {
             content: {
-              'application/json': { schema: schemaToOpenAPI(route.body) },
+              'application/json': { schema: schemaToOpenAPI(topLevelStripped) },
             },
           },
         };
@@ -195,7 +221,7 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
             description,
             content: {
               'application/json': {
-                schema: schemaToOpenAPI(response),
+                schema: schemaToOpenAPI(stripTopLevelComment(response)),
                 ...(example !== undefined ? { example } : undefined),
               },
             },

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

@@ -161,6 +161,7 @@ testCase('simple route', SIMPLE, {
             description: 'foo param',
             required: true,
             schema: {
+              description: 'foo param',
               type: 'string',
             },
           },
@@ -927,6 +928,7 @@ testCase('schema parameter with title tag', TITLE_TAG, {
             description: 'bar param',
             required: true,
             schema: {
+              description: 'bar param',
               title: 'this is a bar parameter',
               type: 'string',
             },