Merge pull request #1309 from nestjs/feat/new-openapi-category

feat(): extract openapi to its own category

Author: kamilmysliwiec

content/cli/overview.md

@@ -58,7 +58,7 @@ Read the sections on [Workspaces](/cli/monorepo) and [Libraries](/cli/libraries)
 
 <app-banner-courses></app-banner-courses>
 
-### CLI command syntax
+#### CLI command syntax
 
 All `nest` commands follow the same format:
 
@@ -80,7 +80,7 @@ $ nest n my-nest-project -d
 
 Most commands, and some options, have aliases. Try running `nest new --help` to see these options and aliases, and to confirm your understanding of the above constructs.
 
-### Command overview
+#### Command overview
 
 Run `nest <command> --help` for any of the following commands to see command-specific options.
 

content/openapi/cli-plugin.md

@@ -0,0 +1,124 @@
+### Plugin
+
+TypeScript's metadata reflection system has several limitations which make it impossible to, for instance, determine what properties a class consists of or recognize whether a given property is optional or required. However, some of these constraints can be addressed at compilation time. Nest provides a plugin that enhances the TypeScript compilation process to reduce the amount of boilerplate code required.
+
+> warning **Hint** This plugin is **opt-in**. If you prefer, you can declare all decorators manually, or only specific decorators where you need them.
+
+#### Overview
+
+The Swagger plugin will automatically:
+
+- annotate all DTO properties with `@ApiProperty` unless `@ApiHideProperty` is used
+- set the `required` property depending on the question mark (e.g. `name?: string` will set `required: false`)
+- set the `type` or `enum` property depending on the type (supports arrays as well)
+- set the `default` property based on the assigned default value
+- set several validation rules based on `class-validator` decorators (if `classValidatorShim` set to `true`)
+- add a response decorator to every endpoint with a proper status and `type` (response model)
+
+Please, note that your filenames **must have** one of the following suffixes: `['.dto.ts', '.entity.ts']` (e.g., `create-user.dto.ts`) in order to be analysed by the plugin.
+
+If you are using a different suffix, you can adjust the plugin's behavior by specifying the `dtoFileNameSuffix` option (see below).
+
+Previously, if you wanted to provide an interactive experience with the Swagger UI,
+you had to duplicate a lot of code to let the package know how your models/components should be declared in the specification. For example, you could define a simple `CreateUserDto` class as follows:
+
+```typescript
+export class CreateUserDto {
+  @ApiProperty()
+  email: string;
+
+  @ApiProperty()
+  password: string;
+
+  @ApiProperty({ enum: RoleEnum, default: [], isArray: true })
+  roles: RoleEnum[] = [];
+
+  @ApiProperty({ required: false, default: true })
+  isEnabled?: boolean = true;
+}
+```
+
+While not a significant issue with medium-sized projects, it becomes verbose & hard to maintain once you have a large set of classes.
+
+By enabling the Swagger plugin, the above class definition can be declared simply:
+
+```typescript
+export class CreateUserDto {
+  email: string;
+  password: string;
+  roles: RoleEnum[] = [];
+  isEnabled?: boolean = true;
+}
+```
+
+The plugin adds appropriate decorators on the fly based on the **Abstract Syntax Tree**. Thus you won't have to struggle with `@ApiProperty` decorators scattered throughout the code.
+
+> warning **Hint** The plugin will automatically generate any missing swagger properties, but if you need to override them, you simply set them explicitly via `@ApiProperty()`.
+
+#### Using the CLI plugin
+
+To enable the plugin, open `nest-cli.json` (if you use [Nest CLI](/cli/overview)) and add the following `plugins` configuration:
+
+```javascript
+{
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "plugins": ["@nestjs/swagger/plugin"]
+  }
+}
+```
+
+You can use the `options` property to customize the behavior of the plugin.
+
+```javascript
+"plugins": [
+  {
+    "name": "@nestjs/swagger/plugin",
+    "options": {
+      "classValidatorShim": false
+    }
+  }
+]
+```
+
+The `options` property has to fulfill the following interface:
+
+```typescript
+export interface PluginOptions {
+  dtoFileNameSuffix?: string[];
+  controllerFileNameSuffix?: string[];
+  classValidatorShim?: boolean;
+}
+```
+
+<table>
+  <tr>
+    <th>Option</th>
+    <th>Default</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>dtoFileNameSuffix</code></td>
+    <td><code>['.dto.ts', '.entity.ts']</code></td>
+    <td>DTO (Data Transfer Object) files suffix</td>
+  </tr>
+  <tr>
+    <td><code>controllerFileNameSuffix</code></td>
+    <td><code>.controller.ts</code></td>
+    <td>Controller files suffix</td>
+  </tr>
+  <tr>
+    <td><code>classValidatorShim</code></td>
+    <td><code>true</code></td>
+    <td>If set to true, the module will reuse <code>class-validator</code> validation decorators (e.g. <code>@Max(10)</code> will add <code>max: 10</code> to schema definition) </td>
+  </tr>
+</table>
+
+If you don't use the CLI but instead have a custom `webpack` configuration, you can use this plugin in combination with `ts-loader`:
+
+```javascript
+getCustomTransformers: (program: any) => ({
+  before: [require('@nestjs/swagger/plugin').before({}, program)]
+}),
+```

content/openapi/decorators.md

@@ -0,0 +1,25 @@
+### 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.
+
+|                          |                     |
+| ------------------------ | ------------------- |
+| `@ApiOperation()`        | Method              |
+| `@ApiResponse()`         | Method / Controller |
+| `@ApiProduces()`         | Method / Controller |
+| `@ApiConsumes()`         | Method / Controller |
+| `@ApiBearerAuth()`       | Method / Controller |
+| `@ApiOAuth2()`           | Method / Controller |
+| `@ApiBasicAuth()`        | Method / Controller |
+| `@ApiSecurity()`         | Method / Controller |
+| `@ApiExtraModels()`      | Method / Controller |
+| `@ApiBody()`             | Method              |
+| `@ApiParam()`            | Method              |
+| `@ApiQuery()`            | Method              |
+| `@ApiHeader()`           | Method / Controller |
+| `@ApiExcludeEndpoint()`  | Method              |
+| `@ApiTags()`             | Method / Controller |
+| `@ApiProperty()`         | Model               |
+| `@ApiPropertyOptional()` | Model               |
+| `@ApiHideProperty()`     | Model               |
+| `@ApiExtension()`        | Method              |

content/openapi/introduction.md

@@ -0,0 +1,69 @@
+### Introduction
+
+The [OpenAPI](https://swagger.io/specification/) specification is a language-agnostic definition format used to describe RESTful APIs. Nest provides a dedicated [module](https://github.com/nestjs/swagger) which allows generating such a specification by leveraging decorators.
+
+#### Installation
+
+To begin using it, we first install the required dependencies.
+
+```bash
+$ npm install --save @nestjs/swagger swagger-ui-express
+```
+
+If you use fastify, install `fastify-swagger` instead of `swagger-ui-express`:
+
+```bash
+$ npm install --save @nestjs/swagger fastify-swagger
+```
+
+#### Bootstrap
+
+Once the installation process is complete, open the `main.ts` file and initialize Swagger using the `SwaggerModule` class:
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const options = new DocumentBuilder()
+    .setTitle('Cats example')
+    .setDescription('The cats API description')
+    .setVersion('1.0')
+    .addTag('cats')
+    .build();
+  const document = SwaggerModule.createDocument(app, options);
+  SwaggerModule.setup('api', app, document);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+The `DocumentBuilder` helps to structure a base document that conforms to the OpenAPI Specification. It provides several methods that allow setting such properties as title, description, version, etc. In order to create a full document (with all HTTP routes defined) we use the `createDocument()` method of the `SwaggerModule` class. This method takes two arguments, an application instance and a Swagger options object.
+
+Once we create a document, we can call the `setup()` method. It accepts:
+
+1. the path to mount the Swagger UI
+2. an application instance
+3. the document object instantiated above
+
+Now you can run the following command to start the HTTP server:
+
+```bash
+$ npm run start
+```
+
+While the application is running, open your browser and navigate to `http://localhost:3000/api`. You should see the Swagger UI.
+
+<figure><img src="/assets/swagger1.png" /></figure>
+
+The `SwaggerModule` automatically reflects all of your endpoints. Note that the Swagger UI is created using either `swagger-ui-express` or `fastify-swagger`, depending on the platform.
+
+> info **Hint** To generate and download a Swagger JSON file, navigate to `http://localhost:3000/api-json` in your browser (assuming that your Swagger documentation is available under `http://localhost:3000/api`).
+
+#### Example
+
+A working example is available [here](https://github.com/nestjs/nest/tree/master/sample/11-swagger).

content/openapi/mapped-types.md

@@ -0,0 +1,130 @@
+### Mapped types
+
+As you build out features like **CRUD** (Create/Read/Update/Delete) it's often useful to construct variants on a base entity type. Nest provides several utility functions that perform type transformations to make this task more convenient.
+
+#### Partial
+
+When building input validation types (also called DTOs), it's often useful to build **create** and **update** variations on the same type. For example, the **create** variant may require all fields, while the **update** variant may make all fields optional.
+
+Nest provides the `PartialType()` utility function to make this task easier and minimize boilerplate.
+
+The `PartialType()` function returns a type (class) with all the properties of the input type set to optional. For example, suppose we have a **create** type as follows:
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  age: number;
+
+  @ApiProperty()
+  breed: string;
+}
+```
+
+By default, all of these fields are required. To create a type with the same fields, but with each one optional, use `PartialType()` passing the class reference (`CreateCatDto`) as an argument:
+
+```typescript
+export class UpdateCatDto extends PartialType(CreateCatDto) {}
+```
+
+> info **Hint** The `PartialType()` function is imported from the `@nestjs/swagger` package.
+
+#### Pick
+
+The `PickType()` function constructs a new type (class) by picking a set of properties from an input type. For example, suppose we start with a type like:
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  age: number;
+
+  @ApiProperty()
+  breed: string;
+}
+```
+
+We can pick a set of properties from this class using the `PickType()` utility function:
+
+```typescript
+export class UpdateCatAgeDto extends PickType(CreateCatDto, ['age'] as const) {}
+```
+
+> info **Hint** The `PickType()` function is imported from the `@nestjs/swagger` package.
+
+#### Omit
+
+The `OmitType()` function constructs a type by picking all properties from an input type and then removing a particular set of keys. For example, suppose we start with a type like:
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  age: number;
+
+  @ApiProperty()
+  breed: string;
+}
+```
+
+We can generate a derived type that has every property **except** `name` as shown below. In this construct, the second argument to `OmitType` is an array of property names.
+
+```typescript
+export class UpdateCatDto extends OmitType(CreateCatDto, ['name'] as const) {}
+```
+
+> info **Hint** The `OmitType()` function is imported from the `@nestjs/swagger` package.
+
+#### Intersection
+
+The `IntersectionType()` function combines two types into one new type (class). For example, suppose we start with two types like:
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  breed: string;
+}
+
+export class AdditionalCatInfo {
+  @ApiProperty()
+  color: string;
+}
+```
+
+We can generate a new type that combines all properties in both types.
+
+```typescript
+export class UpdateCatDto extends IntersectionType(
+  CreateCatDto,
+  AdditionalCatInfo,
+) {}
+```
+
+> info **Hint** The `IntersectionType()` function is imported from the `@nestjs/swagger` package.
+
+#### Composition
+
+The type mapping utility functions are composable. For example, the following will produce a type (class) that has all of the properties of the `CreateCatDto` type except for `name`, and those properties will be set to optional:
+
+```typescript
+export class UpdateCatDto extends PartialType(
+  OmitType(CreateCatDto, ['name'] as const),
+) {}
+```