feat: support per-schema @ContentType JSDoc tags

Author: koralkulacoglu

packages/openapi-generator/src/openapi.ts

@@ -346,9 +346,20 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
       ? {}
       : {
           requestBody: {
-            content: {
-              [contentType]: { schema: schemaToOpenAPI(route.body) },
-            },
+            content: (() => {
+              const emptyBlock: Block = {
+                description: '',
+                tags: [],
+                source: [],
+                problems: [],
+              };
+              const bodyJsdoc = parseCommentBlock(route.body.comment ?? emptyBlock);
+              const requestContentType = bodyJsdoc.tags?.contentType ?? contentType;
+
+              return {
+                [requestContentType]: { schema: schemaToOpenAPI(route.body) },
+              };
+            })(),
           },
         };
 
@@ -394,12 +405,21 @@ function routeToOpenAPI(route: Route): [string, string, OpenAPIV3.OperationObjec
       responses: Object.entries(route.response).reduce((acc, [code, response]) => {
         const description = STATUS_CODES[code] ?? '';
 
+        const emptyBlock: Block = {
+          description: '',
+          tags: [],
+          source: [],
+          problems: [],
+        };
+        const responseJsdoc = parseCommentBlock(response.comment ?? emptyBlock);
+        const responseContentType = responseJsdoc.tags?.contentType ?? contentType;
+
         return {
           ...acc,
           [Number(code)]: {
             description,
             content: {
-              [contentType]: {
+              [responseContentType]: {
                 schema: schemaToOpenAPI(response),
                 ...(example !== undefined ? { example } : undefined),
               },

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

@@ -293,22 +293,29 @@ import * as t from 'io-ts';
 import * as h from '@api-ts/io-ts-http';
 
 /**
- * Route with multipart/form-data content type
+ * Route with per-schema content types
  *
- * @contentType multipart/form-data
  * @operationId api.v1.uploadDocument
  * @tag Document Upload
  */
 export const uploadRoute = h.httpRoute({
   path: '/upload',
   method: 'POST',
   request: h.httpRequest({
+    /**
+     * File upload data
+     * @contentType multipart/form-data
+     */
     body: t.type({
       file: t.unknown,
       documentType: t.string,
     }),
   }),
   response: {
+    /**
+     * Upload success response
+     * @contentType application/xml
+     */
     201: t.type({
       id: t.string,
       success: t.boolean,
@@ -340,7 +347,7 @@ export const createUserRoute = h.httpRoute({
 });
 `;
 
-testCase('route with contentType tag uses multipart/form-data', CONTENT_TYPE_TEST, {
+testCase('route with per-schema contentType tags', CONTENT_TYPE_TEST, {
   openapi: '3.0.3',
   info: {
     title: 'Test',
@@ -349,14 +356,15 @@ testCase('route with contentType tag uses multipart/form-data', CONTENT_TYPE_TES
   paths: {
     '/upload': {
       post: {
-        summary: 'Route with multipart/form-data content type',
+        summary: 'Route with per-schema content types',
         operationId: 'api.v1.uploadDocument',
         tags: ['Document Upload'],
         parameters: [],
         requestBody: {
           content: {
             'multipart/form-data': {
               schema: {
+                description: 'File upload data',
                 type: 'object',
                 properties: {
                   file: {},
@@ -371,8 +379,9 @@ testCase('route with contentType tag uses multipart/form-data', CONTENT_TYPE_TES
           201: {
             description: 'Created',
             content: {
-              'multipart/form-data': {
+              'application/xml': {
                 schema: {
+                  description: 'Upload success response',
                   type: 'object',
                   properties: {
                     id: { type: 'string' },
@@ -428,3 +437,200 @@ testCase('route with contentType tag uses multipart/form-data', CONTENT_TYPE_TES
   },
   components: { schemas: {} },
 });
+
+const PER_RESPONSE_CONTENT_TYPE_TEST = `
+import * as t from 'io-ts';
+import * as h from '@api-ts/io-ts-http';
+
+/**
+ * Upload document with different response content types per status code
+ * @operationId api.v1.uploadDocumentAdvanced
+ * @tag Document Upload
+ */
+export const uploadAdvancedRoute = h.httpRoute({
+  path: '/upload-advanced',
+  method: 'POST',
+  request: h.httpRequest({
+    /**
+     * Multipart form data for file upload
+     * @contentType multipart/form-data
+     */
+    body: t.type({
+      file: t.unknown,
+      documentType: t.string,
+    }),
+  }),
+  response: {
+    /** 
+     * Success response with JSON data
+     * @contentType application/json 
+     */
+    200: t.type({
+      id: t.string,
+      success: t.boolean,
+    }),
+    
+    /** 
+     * Plain text error message
+     * @contentType text/plain 
+     */
+    400: t.string,
+    
+    /** 
+     * File download response
+     * @contentType application/octet-stream
+     */
+    201: t.unknown,
+  },
+});
+
+/**
+ * Standard route with default content types
+ * @operationId api.v1.createUserStandard
+ * @tag User Management
+ */
+export const createUserStandardRoute = h.httpRoute({
+  path: '/users-standard',
+  method: 'POST',
+  request: h.httpRequest({
+    body: t.type({
+      name: t.string,
+      email: t.string,
+    }),
+  }),
+  response: {
+    200: t.type({
+      id: t.string,
+      name: t.string,
+    }),
+    400: t.type({
+      error: t.string,
+    }),
+  },
+});
+`;
+
+testCase('routes with per-response content types', PER_RESPONSE_CONTENT_TYPE_TEST, {
+  openapi: '3.0.3',
+  info: {
+    title: 'Test',
+    version: '1.0.0',
+  },
+  paths: {
+    '/upload-advanced': {
+      post: {
+        summary:
+          'Upload document with different response content types per status code',
+        operationId: 'api.v1.uploadDocumentAdvanced',
+        tags: ['Document Upload'],
+        parameters: [],
+        requestBody: {
+          content: {
+            'multipart/form-data': {
+              schema: {
+                description: 'Multipart form data for file upload',
+                type: 'object',
+                properties: {
+                  file: {},
+                  documentType: { type: 'string' },
+                },
+                required: ['file', 'documentType'],
+              },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'OK',
+            content: {
+              'application/json': {
+                schema: {
+                  description: 'Success response with JSON data',
+                  type: 'object',
+                  properties: {
+                    id: { type: 'string' },
+                    success: { type: 'boolean' },
+                  },
+                  required: ['id', 'success'],
+                },
+              },
+            },
+          },
+          201: {
+            description: 'Created',
+            content: {
+              'application/octet-stream': {
+                schema: {},
+              },
+            },
+          },
+          400: {
+            description: 'Bad Request',
+            content: {
+              'text/plain': {
+                schema: {
+                  description: 'Plain text error message',
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/users-standard': {
+      post: {
+        summary: 'Standard route with default content types',
+        operationId: 'api.v1.createUserStandard',
+        tags: ['User Management'],
+        parameters: [],
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  email: { type: 'string' },
+                },
+                required: ['name', 'email'],
+              },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'OK',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    id: { type: 'string' },
+                    name: { type: 'string' },
+                  },
+                  required: ['id', 'name'],
+                },
+              },
+            },
+          },
+          400: {
+            description: 'Bad Request',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    error: { type: 'string' },
+                  },
+                  required: ['error'],
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  components: { schemas: {} },
+});