@b8n/nestjs-rapidoc

NestJS Rapidoc Module

Nest module for seamless integration with RapiDoc, designed as a drop-in replacement (almost) for the standard OpenAPI (Swagger) module.

Installation

npm i @b8n/nestjs-rapidoc

Quick Start

To set up RapiDoc with your NestJS application, follow the Nest documentation's tutorial for creating an OpenAPI (Swagger) document. Substitute the SwaggerModule with RapidocModule as illustrated in the example below:

import { RapidocModule } from '@b8n/nestjs-rapidoc';
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 config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  RapidocModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

Setup Options

Customize RapiDoc module behavior by providing an options object that adheres to the RapidocCustomOptions interface. Pass this object as the fourth argument to the RapidocModule#setup method.

export interface RapidocCustomOptions {
  useGlobalPrefix?: boolean;
  rapidocOptions?: RapidocUIOptions;
  customCss?: string;
  customCssUrl?: string | string[];
  customJs?: string | string[];
  customJsStr?: string | string[];
  customFavIcon?: string;
  customRapidocAssetsPath?: string;
  customSiteTitle?: string;
  customLogo?: string;
  jsonDocumentUrl?: string;
  yamlDocumentUrl?: string;
  patchDocumentOnRequest?: <TRequest = any, TResponse = any>(req: TRequest, res: TResponse, document: OpenAPIObject) => OpenAPIObject;
}

There are slight changes compared to the SwaggerCustomOptions from the @nestjs/swagger module:

• The addition of customRapidocAssetsPath allows overriding the path to RapiDoc static assets. Correspondingly, the customSwaggerUiPath option has been removed.
• The swaggerUrl has been removed as it is not utilized in the RapidocModule.
• The introduction of customLogo enables changing the default RapiDoc logo in the sidebar. It should be a URL pointing to the custom logo.
• The validatorUrl has been removed as it is not used by RapiDoc.
• Both the url and urls attributes have been removed since they are not utilized by RapiDoc.
• The rapidocOptions attribute has been added to configure the RapiDoc UI. This attribute must adhere to the RapidocUIOptions interface. Essentially, this interface represents a camelCase version (e.g., sort-tags -> sortTags) of the RapiDoc attributes. Correspondingly, the swaggerOptions option has been removed.

  Note: spec-url attribute cannot be configured as the OpenAPI spec of the application is explicitly loaded into RapiDoc upon page load.

Testing

Given the strong reliance on @nestjs/swagger, testing primarily focuses on divergent aspects. To execute E2E tests, use the following command:

npm run test:e2e

For manual testing, launch the example application using:

npm start

Access the RapiDoc UI at http://localhost:9080/api-docs.

License

This module is MIT licensed.