Giới thiệu

Đặc tả OpenAPI là một định dạng mô tả không phụ thuộc ngôn ngữ (language-agnostic), dùng để mô tả các RESTful API. Nest cung cấp một module riêng cho phép bạn tạo ra đặc tả này bằng cách tận dụng decorator.

Cài đặt

Để bắt đầu, trước tiên chúng ta cài đặt dependency cần thiết.

$ npm install --save @nestjs/swagger

$ npm install --save @fastify/static

Khởi tạo (Bootstrap)

Sau khi hoàn tất cài đặt, mở file main.ts và khởi tạo Swagger bằng class SwaggerModule:

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const documentFactory = () => SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, documentFactory);

  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

DocumentBuilder giúp cấu trúc một document nền tuân theo đặc tả OpenAPI. Nó cung cấp nhiều method cho phép bạn thiết lập các thuộc tính như title, description, version. Để tạo ra một document đầy đủ (với tất cả HTTP route được định nghĩa), chúng ta dùng method createDocument() của class SwaggerModule. Method này nhận hai tham số: một instance ứng dụng và một object tùy chọn Swagger. Ngoài ra, chúng ta có thể cung cấp tham số thứ ba, thuộc kiểu SwaggerDocumentOptions. Xem thêm ở phần Document options.

Sau khi tạo document, chúng ta có thể gọi method setup(). Method này nhận:

1. Đường dẫn để mount Swagger UI
2. Một instance ứng dụng
3. Object document đã tạo ở trên
4. Tham số cấu hình tùy chọn (đọc thêm ở đây)

Bây giờ bạn có thể chạy lệnh sau để khởi động HTTP server:

$ npm run start

Trong khi ứng dụng đang chạy, mở browser và truy cập http://localhost:3000/api. Bạn sẽ thấy Swagger UI.

Như bạn thấy, SwaggerModule tự động phản chiếu (reflect) tất cả endpoint của bạn.

SwaggerModule.setup('swagger', app, documentFactory, {
  jsonDocumentUrl: 'swagger/json',
});

app.register(helmet, {
  contentSecurityPolicy: {
    directives: {
      defaultSrc: [`'self'`],
      styleSrc: [`'self'`, `'unsafe-inline'`],
      imgSrc: [`'self'`, 'data:', 'validator.swagger.io'],
      scriptSrc: [`'self'`, `https:`, `'unsafe-inline'`],
    },
  },
});

// Nếu bạn không dùng CSP, có thể dùng cách này:
app.register(helmet, {
  contentSecurityPolicy: false,
});

Tùy chọn cho Document (Document options)

Khi tạo document, bạn có thể cung cấp thêm một số tùy chọn để tinh chỉnh hành vi của thư viện. Các tùy chọn này thuộc kiểu SwaggerDocumentOptions, có thể gồm:

export interface SwaggerDocumentOptions {
  /**
   * List of modules to include in the specification
   */
  include?: Function[];

  /**
   * Additional, extra models that should be inspected and included in the specification
   */
  extraModels?: Function[];

  /**
   * If `true`, swagger will ignore the global prefix set through `setGlobalPrefix()` method
   */
  ignoreGlobalPrefix?: boolean;

  /**
   * If `true`, swagger will also load routes from the modules imported by `include` modules
   */
  deepScanRoutes?: boolean;

  /**
   * Custom operationIdFactory that will be used to generate the `operationId`
   * based on the `controllerKey`, `methodKey`, and version.
   * @default () => controllerKey_methodKey_version
   */
  operationIdFactory?: OperationIdFactory;

  /**
   * Custom linkNameFactory that will be used to generate the name of links
   * in the `links` field of responses
   *
   * @see [Link objects](https://swagger.io/docs/specification/links/)
   *
   * @default () => `${controllerKey}_${methodKey}_from_${fieldKey}`
   */
  linkNameFactory?: (
    controllerKey: string,
    methodKey: string,
    fieldKey: string
  ) => string;

  /*
   * Generate tags automatically based on the controller name.
   * If `false`, you must use the `@ApiTags()` decorator to define tags.
   * Otherwise, the controller name without the suffix `Controller` will be used.
   * @default true
   */
  autoTagControllers?: boolean;
}

Ví dụ, nếu bạn muốn thư viện tạo ra tên operation dạng createUser thay vì UsersController_createUser, bạn có thể thiết lập như sau:

const options: SwaggerDocumentOptions =  {
  operationIdFactory: (
    controllerKey: string,
    methodKey: string
  ) => methodKey
};
const documentFactory = () => SwaggerModule.createDocument(app, config, options);

Standard Schema (Zod, Valibot)

Các decorator route parameter của Nest chấp nhận một schema tương thích Standard Schema qua tùy chọn schema của chúng (xem chương Controllers):

import { z } from 'zod';

const createCatSchema = z.object({
  name: z.string(),
  age: z.number().int().positive(),
  breed: z.string(),
});

@Controller('cats')
export class CatsController {
  @Post()
  create(@Body({ schema: createCatSchema }) createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto);
  }
}

Module Swagger sẽ nhận diện các schema này và chuyển chúng thành request body và parameter trong document được tạo ra.

Các thư viện không cần cấu hình

Nếu thư viện validate của bạn implement extension Standard JSON Schema — nghĩa là schema của nó expose ~standard.jsonSchema — Nest sẽ tự động chuyển đổi, không cần cấu hình gì thêm. Nó yêu cầu target openapi-3.0 và dùng biến thể input hoặc output tùy theo schema đó mô tả request hay response.

Cung cấp một converter

Với các thư viện không expose extension đó, hãy cung cấp một standardSchemaConverter trong SwaggerDocumentOptions. Nó nhận schema thô cùng với schemaType đang được tạo, và trả về schema OpenAPI đã chuyển đổi:

standardSchemaConverter?: (
  schema: unknown,
  options: { schemaType: 'input' | 'output' },
) => { schema: unknown; components?: Record<string, any> } | undefined;

Trả về undefined báo cho Nest biết converter này không xử lý được schema này, nên nó sẽ fallback về cách chuyển đổi mặc định như đã mô tả trên. Đây chính là điều giúp bạn có thể hỗ trợ nhiều thư viện an toàn chỉ từ một converter.

Với Zod, dùng zod-openapi:

$ npm i --save-dev zod-openapi

import { SwaggerDocumentOptions } from '@nestjs/swagger';
import { createSchema } from 'zod-openapi';

const documentOptions: SwaggerDocumentOptions = {
  standardSchemaConverter: (schema, { schemaType }) => {
    const converted = createSchema(schema as never, {
      io: schemaType,
      openapiVersion: '3.0.0',
    });
    return { schema: converted.schema, components: converted.components };
  },
};

const documentFactory = () =>
  SwaggerModule.createDocument(app, config, documentOptions);

Với Valibot, dùng @valibot/to-json-schema:

$ npm i --save-dev @valibot/to-json-schema

import { toJsonSchema } from '@valibot/to-json-schema';

const documentOptions: SwaggerDocumentOptions = {
  standardSchemaConverter: (schema, { schemaType }) => ({
    schema: toJsonSchema(schema as never, {
      target: 'openapi-3.0',
      typeMode: schemaType,
    }),
  }),
};

Chú ý sự khác biệt giữa hai cách trên: createSchema() có thể hoist (đưa lên cấp cao hơn) các định nghĩa tái sử dụng được, nên kết quả của nó mang theo một map components mà bạn truyền qua và Nest sẽ merge vào phần components chung của document. toJsonSchema() trả về một schema tự chứa (self-contained) duy nhất, nên components chỉ đơn giản được bỏ qua.

Hỗ trợ nhiều thư viện cùng lúc

Vì converter nhận schema dưới dạng unknown, bạn có thể rẽ nhánh (branch) theo vendor của schema và hỗ trợ nhiều hơn một thư viện trong cùng ứng dụng. Mỗi Standard Schema đều expose thông tin này tại ~standard.vendor:

import { toJsonSchema } from '@valibot/to-json-schema';
import { createSchema } from 'zod-openapi';

function hasVendor(schema: unknown, vendor: string) {
  return (
    !!schema &&
    typeof schema === 'object' &&
    (schema as { '~standard'?: { vendor?: string } })['~standard']?.vendor ===
      vendor
  );
}

const documentOptions: SwaggerDocumentOptions = {
  standardSchemaConverter: (schema, { schemaType }) => {
    if (hasVendor(schema, 'zod')) {
      const converted = createSchema(schema as never, {
        io: schemaType,
        openapiVersion: '3.0.0',
      });
      return { schema: converted.schema, components: converted.components };
    }

    if (hasVendor(schema, 'valibot')) {
      return {
        schema: toJsonSchema(schema as never, {
          target: 'openapi-3.0',
          typeMode: schemaType,
        }),
      };
    }

    // Not handled here - let Nest fall back to native conversion
    return undefined;
  },
};

Tùy chọn thiết lập (Setup options)

Bạn có thể cấu hình Swagger UI bằng cách truyền một object tùy chọn tuân theo interface SwaggerCustomOptions, làm tham số thứ tư của method SwaggerModule#setup.

export interface SwaggerCustomOptions {
  /**
   * If `true`, Swagger resources paths will be prefixed by the global prefix set through `setGlobalPrefix()`.
   * Default: `false`.
   * @see https://docs.nestjs.com/faq/global-prefix
   */
  useGlobalPrefix?: boolean;

  /**
   * If `false`, the Swagger UI will not be served. Only API definitions (JSON and YAML)
   * will be accessible (on `/{path}-json` and `/{path}-yaml`). To fully disable both the Swagger UI and API definitions, use `raw: false`.
   * Default: `true`.
   * @deprecated Use `ui` instead.
   */
  swaggerUiEnabled?: boolean;

  /**
   * If `false`, the Swagger UI will not be served. Only API definitions (JSON and YAML)
   * will be accessible (on `/{path}-json` and `/{path}-yaml`). To fully disable both the Swagger UI and API definitions, use `raw: false`.
   * Default: `true`.
   */
  ui?: boolean;

  /**
   * If `true`, raw definitions for all formats will be served.
   * Alternatively, you can pass an array to specify the formats to be served, e.g., `raw: ['json']` to serve only JSON definitions.
   * If omitted or set to an empty array, no definitions (JSON or YAML) will be served.
   * Use this option to control the availability of Swagger-related endpoints.
   * Default: `true`.
   */
  raw?: boolean | Array<'json' | 'yaml'>;

  /**
   * Url point the API definition to load in Swagger UI.
   */
  swaggerUrl?: string;

  /**
   * Path of the JSON API definition to serve.
   * Default: `<path>-json`.
   */
  jsonDocumentUrl?: string;

  /**
   * Path of the YAML API definition to serve.
   * Default: `<path>-yaml`.
   */
  yamlDocumentUrl?: string;

  /**
   * Hook allowing to alter the OpenAPI document before being served.
   * It's called after the document is generated and before it is served as JSON & YAML.
   */
  patchDocumentOnRequest?: <TRequest = any, TResponse = any>(
    req: TRequest,
    res: TResponse,
    document: OpenAPIObject
  ) => OpenAPIObject;

  /**
   * If `true`, the selector of OpenAPI definitions is displayed in the Swagger UI interface.
   * Default: `false`.
   */
  explorer?: boolean;

  /**
   * Additional Swagger UI options
   */
  swaggerOptions?: SwaggerUiOptions;

  /**
   * Custom CSS styles to inject in Swagger UI page.
   */
  customCss?: string;

  /**
   * URL(s) of a custom CSS stylesheet to load in Swagger UI page.
   */
  customCssUrl?: string | string[];

  /**
   * URL(s) of custom JavaScript files to load in Swagger UI page.
   */
  customJs?: string | string[];

  /**
   * Custom JavaScript scripts to load in Swagger UI page.
   */
  customJsStr?: string | string[];

  /**
   * Custom favicon for Swagger UI page.
   */
  customfavIcon?: string;

  /**
   * Custom title for Swagger UI page.
   */
  customSiteTitle?: string;

  /**
   * File system path (ex: ./node_modules/swagger-ui-dist) containing static Swagger UI assets.
   */
  customSwaggerUiPath?: string;

  /**
   * @deprecated This property has no effect.
   */
  validatorUrl?: string;

  /**
   * @deprecated This property has no effect.
   */
  url?: string;

  /**
   * @deprecated This property has no effect.
   */
  urls?: Record<'url' | 'name', string>[];
}

const options: SwaggerCustomOptions = {
  ui: false, // Swagger UI is disabled
  raw: ['json'], // JSON API definition is still accessible (YAML is disabled)
};
SwaggerModule.setup('api', app, options);

Ví dụ

Một ví dụ hoạt động đầy đủ có sẵn tại đây.