Merge branch 'master' of https://github.com/nestjs/docs.nestjs.com

Author: kamilmysliwiec

content/fundamentals/unit-testing.md

@@ -302,7 +302,7 @@ The compiled module has several useful methods, as described in the following ta
 
 #### Testing request-scoped instances
 
-[Request-scoped](/fundamentals/injection-scope) providers are created uniquely for each incoming **request**. The instance is garbage-collected after the request has completed processing. This poses a problem, because we can't access a dependency injection sub-tree generated specifically for a tested request.
+[Request-scoped](/fundamentals/injection-scopes) providers are created uniquely for each incoming **request**. The instance is garbage-collected after the request has completed processing. This poses a problem, because we can't access a dependency injection sub-tree generated specifically for a tested request.
 
 We know (based on the sections above) that the `resolve()` method can be used to retrieve a dynamically instantiated class. Also, as described <a href="https://docs.nestjs/com/fundamentals/module-ref#resolving-scoped-providers">here</a>, we know we can pass a unique context identifier to control the lifecycle of a DI container sub-tree. How do we leverage this in a testing context?
 

content/graphql/quick-start.md

@@ -1,8 +1,10 @@
-### Quick start
+## Harnessing the power of TypeScript & GraphQL
 
-GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. It's an elegant approach that solves many problems typically found with REST APIs. For background, we suggest reading this [comparison](https://dev-blog.apollodata.com/graphql-vs-rest-5d425123e34b) between GraphQL and REST. In this chapter, we assume a basic understanding of GraphQL, and focus on how to work with the built-in `@nestjs/graphql` module.
+[GraphQL](https://graphql.org/) is a powerful query language for APIs and a runtime for fulfilling those queries with your existing data. It's an elegant approach that solves many problems typically found with REST APIs. For background, we suggest reading this [comparison](https://dev-blog.apollodata.com/graphql-vs-rest-5d425123e34b) between GraphQL and REST. 
 
-The `GraphQLModule` is a wrapper around the [Apollo](https://www.apollographql.com/) server. We use this proven GraphQL package to provide a way to use GraphQL with Nest.
+GraphQL combined with [TypeScript](https://www.typescriptlang.org/) helps you develop better type safety with your GraphQL queries, giving you get end-to-end typing.
+
+In this chapter, we assume a basic understanding of GraphQL, and focus on how to work with the built-in `@nestjs/graphql` module. The `GraphQLModule` is a wrapper around the [Apollo](https://www.apollographql.com/) server. We use this proven GraphQL package to provide a way to use GraphQL with Nest.
 
 #### Installation
 
@@ -22,7 +24,7 @@ In the **schema first** approach, the source of truth is a GraphQL SDL (Schema D
 
 In the **code first** approach, you use decorators and TypeScript classes to generate the corresponding GraphQL schema. This approach is useful if you prefer to work exclusively with TypeScript and avoid context switching between language syntaxes.
 
-#### Getting started
+#### Getting started with GraphQL & TypeScript
 
 Once the packages are installed, we can import the `GraphQLModule` and configure it with the `forRoot()` static method.
 

content/microservices/grpc.md

@@ -161,7 +161,7 @@ export class HeroController {
 @@switch
 @Controller()
 export class HeroController {
-  @GrpcMethod('HeroService)
+  @GrpcMethod('HeroService')
   findOne(data, metadata) {
     const items = [
       { id: 1, name: 'John' },

content/microservices/kafka.md

@@ -71,6 +71,16 @@ The `options` property is specific to the chosen transporter. The <strong>Kafka<
         >here</a
       >)</td>
   </tr>
+  <tr>
+    <td><code>subscribe</code></td>
+    <td>Subscribe configuration options (read more
+      <a
+        href="https://kafka.js.org/docs/consuming#frombeginning"
+        rel="nofollow"
+        target="blank"
+        >here</a
+      >)</td>
+  </tr>
   <tr>
     <td><code>producer</code></td>
     <td>Producer configuration options (read more

content/recipes/swagger.md

@@ -23,10 +23,10 @@ Once the installation process is complete, open the `main.ts` file and initializ
 ```typescript
 import { NestFactory } from '@nestjs/core';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
-import { ApplicationModule } from './app.module';
+import { AppModule } from './app.module';
 
 async function bootstrap() {
-  const app = await NestFactory.create(ApplicationModule);
+  const app = await NestFactory.create(AppModule);
 
   const options = new DocumentBuilder()
     .setTitle('Cats example')
@@ -158,6 +158,80 @@ With `isArray` set to **true**, the `enum` can be selected as a **multi-select**
 
 <figure><img src="/assets/enum_query_array.gif" /></figure>
 
+#### Enums schema
+
+By default, the `enum` property will add a raw definition of [Enum](https://swagger.io/docs/specification/data-models/enums/) on the `parameter`.
+
+```yaml
+CatDetail:
+  type: 'object'
+  properties:
+    ...
+    - breed:
+        type: 'string'
+        enum:
+          - Persian
+          - Tabby
+          - Siamese
+```
+
+The above specification works fine for most cases. However, if you are utilizing a tool that takes the specification as **input** and generates **client-side** code, you might run into a problem with the generated code containing duplicated `enums`. Consider the following code snippet: 
+
+```typescript
+// generated client-side code
+export class CatDetail {
+   breed: CatDetailEnum;
+}
+
+export class CatInformation {
+  breed: CatInformationEnum;
+}
+
+export enum CatDetailEnum {
+  Persian = 'Persian',
+  Tabby = 'Tabby',
+  Siamese = 'Siamese'
+}
+
+export enum CatInformationEnum {
+  Persian = 'Persian',
+  Tabby = 'Tabby',
+  Siamese = 'Siamese'
+}
+```
+
+> info **Hint** The above snippet is generated using a tool called [NSwag](https://github.com/RicoSuter/NSwag).
+
+You can see that now you have two `enums` that are exactly the same. 
+To address this issue, you can pass an `enumName` next to `enum` property in your decorator.
+
+```typescript
+export class CatDetail {
+   @ApiProperty({ enum: CatBreed, enumName: 'CatBreed' })
+   breed: CatBreed;
+}
+```
+
+`enumName` enables `nestjs/swagger` to turn `CatBreed` into its own `schema` which in turns makes `CatBreed` reusable. The specification will look like the following:
+
+```yaml
+CatDetail:
+  type: 'object'
+  properties:
+    ...
+    - breed:
+        schema:
+          $ref: '#/components/schemas/CatBreed'
+CatBreed:
+  type: string
+  enum:
+    - Persian
+    - Tabby
+    - Siamese
+```
+
+> info **Hint** Any **decorator** that takes `enum` as a property will also take `enumName`.
+
 #### Arrays
 
 When the property is an array, we must manually indicate the array type as shown below:
@@ -279,10 +353,10 @@ You can setup multiple specifications support as shown below:
 ```typescript
 import { NestFactory } from '@nestjs/core';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
-import { ApplicationModule } from './app.module';
+import { AppModule } from './app.module';
 
 async function bootstrap() {
-  const app = await NestFactory.create(ApplicationModule);
+  const app = await NestFactory.create(AppModule);
 
   /**
    * createDocument(application, configurationOptions, extraOptions);
@@ -548,6 +622,14 @@ class FileUploadDto {
 }
 ```
 
+#### Extensions
+
+To add an Extension to a request use the `@ApiExtension()` decorator. The extension name must be prefixed with `x-`.
+
+```typescript
+@ApiExtension('x-foo', { hello: 'world' })
+```
+
 #### Decorators
 
 All of the available OpenAPI decorators have an `Api` prefix to distinguish them from the core decorators. Below is a full list of the exported decorators along with a designation of the level at which the decorator may be applied.
@@ -572,6 +654,7 @@ All of the available OpenAPI decorators have an `Api` prefix to distinguish them
 | `@ApiProperty()`         | Model               |
 | `@ApiPropertyOptional()` | Model               |
 | `@ApiHideProperty()`     | Model               |
+| `@ApiExtension()`        | Method              |
 
 #### Plugin
 

content/techniques/file-upload.md

@@ -122,6 +122,8 @@ MulterModule.register({
 });
 ```
 
+> info **Hint** The `MulterModule` class is exported from the `@nestjs/platform-express` package.
+
 #### Async configuration
 
 When you need to set `MulterModule` options asynchronously instead of statically, use the `registerAsync()` method. As with most dynamic modules, Nest provides several techniques to deal with async configuration.

content/techniques/sql.md

@@ -614,13 +614,13 @@ Our factory behaves like any other [asynchronous provider](https://docs.nestjs.c
 ```typescript
 TypeOrmModule.forRootAsync({
   imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
+  useFactory: (configService: ConfigService) => ({
     type: 'mysql',
-    host: configService.getString('HOST'),
-    port: configService.getString('PORT'),
-    username: configService.getString('USERNAME'),
-    password: configService.getString('PASSWORD'),
-    database: configService.getString('DATABASE'),
+    host: configService.get<string>('HOST'),
+    port: configService.get<string>('PORT'),
+    username: configService.get<string>('USERNAME'),
+    password: configService.get<string>('PASSWORD'),
+    database: configService.get<string>('DATABASE'),
     entities: [__dirname + '/**/*.entity{.ts,.js}'],
     synchronize: true,
   }),
@@ -1149,13 +1149,13 @@ Our factory behaves like any other [asynchronous provider](https://docs.nestjs.c
 ```typescript
 SequelizeModule.forRootAsync({
   imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
+  useFactory: (configService: ConfigService) => ({
     dialect: 'mysql',
-    host: configService.getString('HOST'),
-    port: configService.getString('PORT'),
-    username: configService.getString('USERNAME'),
-    password: configService.getString('PASSWORD'),
-    database: configService.getString('DATABASE'),
+    host: configService.get<string>('HOST'),
+    port: configService.get<string>('PORT'),
+    username: configService.get<string>('USERNAME'),
+    password: configService.get<string>('PASSWORD'),
+    database: configService.get<string>('DATABASE'),
     models: [],
   }),
   inject: [ConfigService],