@brakebein/nestjs-redoc

NestJS-Redoc

ReDoc powered frontend for your NestJS API spec

⚡ Features | 🗿 Installation | ❓ How to use | 👨‍💻👩‍💻 Contributors | 📜 Changelog | 📋 ToDo

📒 This is a ReDoc powered frontend for your NestJS API spec.

⚡ Features

• Customizable theme
• It's almost a drop in replacement for you current swagger UI, you only need to import this package and modify any settings you may want to change (e.g: Page title, ReDoc options)

🗿 Installation

Using npm: npm i nestjs-redoc

Using yarn: yarn add nestjs-redoc

❓ How to use

You need to install the Swagger Module first if you want to get definitions updated with your project.

In future versions you will be able to pass a URL parameter as document, but for the moment you need this document object from the swagger module

const options = new DocumentBuilder()
  .setTitle('Look, i have a title')
  .setDescription('A very nice description')
  .setBasePath('/api/v1')
  .build();
const document = SwaggerModule.createDocument(app, options);

Then add the following example code.

Note: All properties are optional, if you don't specify a title we will fallback to the one you used in your DocumentBuilder instance.

const redocOptions: RedocOptions = {
  title: 'Hello Nest',
  logo: {
    url: 'https://redocly.github.io/redoc/petstore-logo.png',
    backgroundColor: '#F0F0F0',
    altText: 'PetStore logo'
  },
  sortPropsAlphabetically: true,
  hideDownloadButton: false,
  hideHostname: false,
  auth: {
    enabled: true,
    user: 'admin',
    password: '123'
  },
  tagGroups: [
    {
      name: 'Core resources',
      tags: ['cats'],
    },
  ],
};
// Instead of using SwaggerModule.setup() you call this module
await RedocModule.setup('/docs', app, document, redocOptions);

Available options

Redoc Options

Option	Description	Type	Note
title	Web site title (e.g: ReDoc documentation)	string
favicon	Web site favicon URL	string	Fallbacks to the document title if not set
logo	Logo options	LogoOptions	See LogoOptions table
theme	Theme options	ThemeOptions	See ThemeOptions info
untrustedSpec	If set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS, by default is false	boolean
supressWarnings	If set, warnings are not rendered at the top of documentation (they are still logged to the console)	boolean
hideHostname	If set, the protocol and hostname won't be shown in the operation definition	boolean
expandResponses	Specify which responses to expand by default by response codes, values should be passed as comma-separated list without spaces (e.g: 200, 201, "all")	string
requiredPropsFirst	If set, show required properties first ordered in the same order as in required array	boolean
sortPropsAlphabetically	If set, propeties will be sorted alphabetically	boolean
showExtensions	If set the fields starting with "x-" will be shown, can be a boolean or a string with names of extensions to display	boolean
noAutoAuth	If set, redoc won't inject authentication section automatically	boolean
pathInMiddlePanel	If set, path link and HTTP verb will be shown in the middle panel instead of the right one	boolean
hideLoading	If set, loading spinner animation won't be shown	boolean
nativeScrollbars	If set, a native scrollbar will be used instead of perfect-scroll, this can improve performance of the frontend for big specs	boolean
hideDownloadButton	This will hide the "Download spec" button, it only hides the button	boolean
disableSearch	If set, the search bar will be disabled	boolean
onlyRequiredInSamples	Shows only required fileds in request samples	boolean
auth	Auth options	AuthOptions	See AuthOptions info
AuthOptions info
enabled	If enabled, a prompt will pop out asking for authentication details, default: false	boolean
user	User name, default: admin	string
password	User password, default: 123	string
tagGroups	Tag groups options	TagGroupOptions[]	See Tag Group options
Tag Group options info
name	Tag name	string
tags	Tag collection	string[]
redocVersion	Set an specific redoc version	string,number	By default it's "latest"

Note: If you want to change your ReDoc theme settings, take a look at the official ReDoc documentation: https://github.com/Redocly/redoc/blob/master/src/theme.ts

Apply the properties defined in ResolvedThemeInterface to the key called "theme" in the redoc options

Logo options

Option	Description	Type	Example
url	The URL pointing to the spec Logo, must be in the format of a URL and an absolute URL	string
backgroundColor	Background color to be used, must be RGB color in hexadecimal format (e.g: #008080)	string	#F0F0F0
altText	Alt tag for Logo	string	PetStore
href	href tag for Logo, it defaults to the host used for your API spec	string

👨‍💻👩‍💻 Contributors

• Special thanks to Jay McDoniel (jmcdo29) who helped with code refactoring and unit tests! 👏
• @joemaidman

📜 Changelog

Bellow are a list of changes, some might go undocumented

• 1.0.0 - First release
• 1.1.0 - Minor changes, nothing too important
• 1.2.0 - Added unit tests, refactored code
• 1.2.1 - Updated to work with the latest version of nest swagger module
• 1.2.2 - Fixed issue with URL on Windows
• 1.3.0 - Added favicon option (by @joemaidman)
• 2.0.0 - Added authentication option, fixed issues with CSP and nestjs version compatibility issues
• 2.1.0 - Added x-tagGroups extension property
• 2.1.1 - Fixed CSP issue on Safari browser
• 2.2.0 - Added version property, this way you can pin redoc to a specific version
• 2.2.2 - Updated to support Nest 8
• 2.3.0 - Updated to support Nest 9, removed padding from logo image

📋 ToDo

• Add Fastify support
• Add the option to use a spec URL instead of document
• Fix tests