Merge pull request #2871 from lit26/feature/add-response-example

feat: add response example

Author: kamilmysliwiec

lib/decorators/api-response.decorator.ts

@@ -14,6 +14,7 @@ export interface ApiResponseMetadata
   type?: Type<unknown> | Function | [Function] | string;
   isArray?: boolean;
   description?: string;
+  example?: any;
 }
 
 export interface ApiResponseSchemaHost

lib/services/mimetype-content-wrapper.ts

@@ -1,12 +1,21 @@
 import { ContentObject } from '../interfaces/open-api-spec.interface';
 
+function removeUndefinedKeys(obj: { [x: string]: any }) {
+  Object.entries(obj).forEach(([key, value]) => {
+    if (value === undefined) {
+      delete obj[key];
+    }
+  });
+  return obj;
+}
+
 export class MimetypeContentWrapper {
   wrap(
     mimetype: string[],
     obj: Record<string, any>
   ): Record<'content', ContentObject> {
     const content = mimetype.reduce(
-      (acc, item) => ({ ...acc, [item]: obj }),
+      (acc, item) => ({ ...acc, [item]: removeUndefinedKeys(obj) }),
       {}
     );
     return { content };

lib/services/response-object-mapper.ts

@@ -1,5 +1,5 @@
 import { omit } from 'lodash';
-import { ApiResponseSchemaHost } from '../decorators';
+import { ApiResponseMetadata, ApiResponseSchemaHost } from '../decorators';
 import { getSchemaPath } from '../utils';
 import { MimetypeContentWrapper } from './mimetype-content-wrapper';
 
@@ -19,7 +19,8 @@ export class ResponseObjectMapper {
           items: {
             $ref: getSchemaPath(name)
           }
-        }
+        },
+        example: response.example
       })
     };
   }
@@ -30,20 +31,25 @@ export class ResponseObjectMapper {
       ...this.mimetypeContentWrapper.wrap(produces, {
         schema: {
           $ref: getSchemaPath(name)
-        }
+        },
+        example: response.example
       })
     };
   }
 
-  wrapSchemaWithContent(response: ApiResponseSchemaHost, produces: string[]) {
-    if (!response.schema) {
+  wrapSchemaWithContent(
+    response: ApiResponseSchemaHost & ApiResponseMetadata,
+    produces: string[]
+  ) {
+    if (!response.schema && !response.example) {
       return response;
     }
     const content = this.mimetypeContentWrapper.wrap(produces, {
-      schema: response.schema
+      schema: response.schema,
+      example: response.example
     });
     return {
-      ...omit(response, 'schema'),
+      ...omit(response, ['schema', 'example']),
       ...content
     };
   }

test/explorer/swagger-explorer.spec.ts

@@ -103,7 +103,11 @@ describe('SwaggerExplorer', () => {
       @ApiOperation({ summary: 'Create foo' })
       @ApiCreatedResponse({
         type: Foo,
-        description: 'Newly created Foo object'
+        description: 'Newly created Foo object',
+        example: {
+          id: 'foo',
+          name: 'Foo'
+        }
       })
       create(
         @Body() createFoo: CreateFoo,
@@ -144,7 +148,11 @@ describe('SwaggerExplorer', () => {
       @Post('foos')
       @ApiCreatedResponse({
         type: Foo,
-        description: 'Newly created Foo object'
+        description: 'Newly created Foo object',
+        example: {
+          id: 'foo',
+          name: 'Foo'
+        }
       })
       create(
         @Body() createFoo: CreateFoo,
@@ -164,7 +172,11 @@ describe('SwaggerExplorer', () => {
       static [METADATA_FACTORY_NAME]() {
         return {
           create: {
-            summary: 'Create foo'
+            summary: 'Create foo',
+            example: {
+              id: 'foo',
+              name: 'Foo'
+            }
           },
           find: {
             summary: 'List all Foos',
@@ -315,7 +327,8 @@ describe('SwaggerExplorer', () => {
       ).toEqual({
         schema: {
           $ref: '#/components/schemas/Foo'
-        }
+        },
+        example: { id: 'foo', name: 'Foo' }
       });
 
       // GET