docs: add example showing how to set headers (#399)

Author: BenLorantfy

packages/example/src/app.spec.ts

@@ -19,7 +19,7 @@ afterEach(async () => {
 });
 
 describe('GET /api/people', () => {
-  it('should return a list of people', () => {
+  test('returns a list of people', () => {
     return request(app.getHttpServer())
       .get('/api/people')
       .expect(200)
@@ -29,4 +29,16 @@ describe('GET /api/people', () => {
         expect(res.body.data.length).toBeGreaterThan(0);
       });
   });
+
+  test('issue#327 - example showing headers', () => {
+    return request(app.getHttpServer())
+      .get('/api/starships/headers-example')
+      .expect(200)
+      .expect((res) => {
+        expect(res.body).toHaveProperty('data');
+        expect(Array.isArray(res.body.data)).toBe(true);
+        expect(res.body.data.length).toBeGreaterThan(0);
+        expect(res.headers['x-example']).toBe('example');
+      });
+  })
 });

packages/example/src/starships/starships.controller.ts

@@ -1,7 +1,8 @@
-import { Controller, Get, Post, Body } from '@nestjs/common';
+import { Controller, Get, Post, Body, Res } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
 import { ZodResponse } from 'nestjs-zod';
 import { CreateStarshipFormDto, StarshipDto, StarshipListDto, Starship } from './starships.dto';
+import { Response } from 'express';
 
 @ApiTags('Starships')
 @Controller('api/starships')
@@ -83,4 +84,31 @@ export class StarshipsController {
 
     return newStarship;
   }
+
+  /**
+   * This example shows how to use the @Res decorator to set headers on the
+   * response.  Note that in order for `@ZodResponse` to work, we need to return
+   * the data from the function and use `passthrough: true`.  We can't use
+   * `res.send()`!  `res.send()` bypasses the zod nestjs interceptor 
+   * 
+   * For more information, search `passthrough` in the zod documentation page
+   * for controllers here: https://docs.nestjs.com/controllers
+   * 
+   * > Nest detects when the handler is using either @Res() or @Next(), indicating
+   * > you have chosen the library-specific option. If both approaches are used at
+   * > the same time, the Standard approach is automatically disabled for this
+   * > single route and will no longer work as expected. To use both approaches at
+   * > the same time (for example, by injecting the response object to only set
+   * > cookies/headers but still leave the rest to the framework), you must set
+   * > the passthrough option to true in the @Res({ passthrough: true })
+   * > decorator.
+   */
+  @Get('headers-example')
+  @ZodResponse({ type: StarshipListDto, description: 'List of all starships' })
+  getStarships2(@Res({ passthrough: true }) res: Response) {
+    res.header('X-Example', 'example');
+    return {
+      data: this.mockStarships,
+    };
+  }
 }