NestJS ReDoc

A NestJS Frontend for your OpenAPI Specs powered by ReDoc

Installation

npm i nest-redoc

Usage

1import {RedocModule} from "./redoc.module";
2
3async
4run = () => {
5
6    // create the NestJS application
7    const app = await NestFactory.create(AppModule, { ... });
8    
9    // create the document builder
10    const config = RedocModule.createDocumentBuilder() // OR: new DocumentBuilder()
11      .setTitle('Cats');
12    
13    // create the document from the config
14    const document = RedocModule.createDocument(app, config.build()); // OR: SwaggerModule.createDocument(app, config.build())
15		
16    // setup the redoc module
17    await RedocModule.setup('/redoc', app, document, { ... }); 			
18		
19    // start application
20    await app.listen(3001); 
21		
22}
23
24run();

Options

1/**
2 * Sets the redoc version that should be used through the ReDoc CDN
3 * @see https://github.com/Redocly/redoc/tags
4 *
5 * @example v2.1.2
6 * @default latest
7 */
8redocVersion: string;
9
10/**
11 * Frontend Title (e.g: Cats)
12 */
13title: string;
14
15/**
16 * Frontend Favicon URL or Buffer
17 */
18favicon: string|Buffer|null;
19
20/**
21 * Logo options
22 */
23logo: {
24
25    /**
26     * Defines the url of the logo that should be displayed on the frontend. Must be in the format of a URL and has to be absolute
27     */
28    url: string|Buffer;
29    
30    /**
31     * HEX Color that should be used for the background
32     */
33    backgroundColor: string;
34    
35    /**
36     * Alt text for the logo
37     */
38    altText: string;
39    
40    /**
41     * href attribute for the logo
42     * @default self
43     */
44    href: string;
45	
46};
47
48/**
49 * Custom theme options for the ReDoc frontend
50 * @see https://redocly.com/docs/redoc/config/#theme-settings
51 */
52theme: RedocTheme;
53
54/**
55 * Disables search indexing and hides the search box from the API documentation page.
56 * @see https://redocly.com/docs/redoc/config/#disablesearch
57 *
58 * @default false
59 */
60disableSearch: boolean;
61
62/**
63 * Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search.
64 * @see https://redocly.com/docs/redoc/config/#mincharacterlengthtoinitsearch
65 *
66 * @default 3
67 */
68minCharacterLengthToInitSearch: number;
69
70/**
71 * Enables or disables expanding default server variables.
72 * @see https://redocly.com/docs/redoc/config/#expanddefaultservervariables
73 *
74 * @default false
75 */
76expandDefaultServerVariables: boolean;
77
78/**
79 * Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example expandResponses='200,201'. Special value 'all' expands all responses by default.
80 * Be careful: this option can slow down documentation rendering time.
81 * @see https://redocly.com/docs/redoc/config/#expandresponses
82 */
83expandResponses: string[];
84
85/**
86 * Automatically expands the single field in a schema.
87 * @see https://redocly.com/docs/redoc/config/#expandsingleschemafield
88 *
89 * @default false
90 */
91expandSingleSchemaField: boolean;
92
93/**
94 * Hides the 'Download' button for saving the API definition source file. This setting does not make the API definition private; it just hides the button.
95 * @see https://redocly.com/docs/redoc/config/#hidedownloadbutton
96 *
97 * @default false
98 */
99hideDownloadButton: boolean;
100
101/**
102 * If set to true, the protocol and hostname are not shown in the operation definition.
103 * @see https://redocly.com/docs/redoc/config/#hidehostname
104 *
105 * @default false
106 */
107hideHostname: boolean;
108
109/**
110 * Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.
111 * @see https://redocly.com/docs/redoc/config/#hideloading
112 *
113 * @default false
114 */
115hideLoading: boolean;
116
117/**
118 * Hides request payload examples.
119 * @see https://redocly.com/docs/redoc/config/#hiderequestpayloadsample
120 *
121 * @default false
122 */
123hideRequestPayloadSample: boolean;
124
125/**
126 * If set to true, the description for oneOf/anyOf object is not shown in the schema.
127 * @see https://redocly.com/docs/redoc/config/#hideoneofdescription
128 *
129 * @default false
130 */
131hideOneOfDescription: boolean;
132
133/**
134 * If set to true, the pattern is not shown in the schema.
135 * @see https://redocly.com/docs/redoc/config/#hideschemapattern
136 *
137 * @default false
138 */
139hideSchemaPattern: boolean;
140
141/**
142 * Hides the schema titles next to the type.
143 * @see https://redocly.com/docs/redoc/config/#hideschematitles
144 *
145 * @default false
146 */
147hideSchemaTitles: boolean;
148
149/**
150 * Hides the Security panel section.
151 * @see https://redocly.com/docs/redoc/config/#hidesecuritysection
152 *
153 * @default false
154 */
155hideSecuritySection: boolean;
156
157/**
158 * Hides the request sample tab for requests with only one sample.
159 * @see https://redocly.com/docs/redoc/config/#hidesinglerequestsampletab
160 *
161 * @default false
162 */
163hideSingleRequestSampleTab: boolean;
164
165/**
166 * Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value all that expands all levels.
167 * @see https://redocly.com/docs/redoc/config/#jsonsampleexpandlevel
168 *
169 * @default 2
170 */
171jsonSampleExpandLevel: number|string;
172
173/**
174 * Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.
175 * @see https://redocly.com/docs/redoc/config/#maxdisplayedenumvalues
176 *
177 * @default null
178 */
179maxDisplayedEnumValues: number|null;
180
181/**
182 * If set to true, selecting an expanded item in the sidebar twice collapses it.
183 * @see https://redocly.com/docs/redoc/config/#menutoggle
184 *
185 * @default true
186 */
187menuToggle: boolean;
188
189/**
190 * If set to true, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.
191 * @see https://redocly.com/docs/redoc/config/#nativescrollbars
192 *
193 * @default false
194 */
195nativeScrollbars: boolean;
196
197/**
198 * Shows only required fields in request samples.
199 * @see https://redocly.com/docs/redoc/config/#onlyrequiredinsamples
200 *
201 * @default false
202 */
203onlyRequiredInSamples: boolean;
204
205/**
206 * Shows the path link and HTTP verb in the middle panel instead of the right panel.
207 * @see https://redocly.com/docs/redoc/config/#pathinmiddlepanel
208 *
209 * @default false
210 */
211pathInMiddlePanel: boolean;
212
213/**
214 * If set, the payload sample is inserted at the specified index. If there are N payload samples and the value configured here is bigger than N, the payload sample is inserted last. Indexes start from 0.
215 * @see https://redocly.com/docs/redoc/config/#payloadsampleidx
216 */
217payloadSampleIdx: any;
218
219/**
220 * Shows required properties in schemas first, ordered in the same order as in the required array.
221 * @see https://redocly.com/docs/redoc/config/#requiredpropsfirst
222 *
223 * @default false
224 */
225requiredPropsFirst: boolean;
226
227/**
228 * Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.
229 * @see https://redocly.com/docs/redoc/config/#schemaexpansionlevel
230 *
231 * @default 0
232 */
233schemaExpansionLevel: number|'all';
234
235/**
236 * Specifies a vertical scroll-offset. This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.
237 *
238 * Note that you can specify the scrollYOffset value in any of the following ways:
239 *
240 * > as a number - a fixed number of pixels to be used as the offset.
241 * > as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset.
242 * > a function (advanced) - a getter function. Must return a number representing the offset (in pixels).
243 * @see https://redocly.com/docs/redoc/config/#scrollyoffset
244 *
245 */
246scrollYOffset: any;
247
248/**
249 * Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to true, all specification extensions are shown.
250 * @see https://redocly.com/docs/redoc/config/#showextensions
251 *
252 * @default false
253 */
254showExtensions: boolean|string[];
255
256/**
257 * Shows object schema example in the properties; default false.
258 * @see https://redocly.com/docs/redoc/config/#showobjectschemaexamples
259 *
260 * @default false
261 */
262showObjectSchemaExamples: boolean;
263
264/**
265 * When set to true, shows the HTTP request method for webhooks in operations and in the sidebar.
266 * @see https://redocly.com/docs/redoc/config/#showwebhookverb
267 *
268 * @default false
269 */
270showWebhookVerb: boolean;
271
272/**
273 * Shows only unique oneOf types in the label without titles.
274 * @see https://redocly.com/docs/redoc/config/#simpleoneoftypelabel
275 *
276 * @default false
277 */
278simpleOneOfTypeLabel: boolean;
279
280/**
281 * When set to true, sorts all enum values in all schemas alphabetically.
282 * @see https://redocly.com/docs/redoc/config/#sortenumvaluesalphabetically
283 *
284 * @default false
285 */
286sortEnumValuesAlphabetically: boolean;
287
288/**
289 * When set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically.
290 * @see https://redocly.com/docs/redoc/config/#sortoperationsalphabetically
291 *
292 * @default false
293 */
294sortOperationsAlphabetically: boolean;
295
296/**
297 * When set to true, sorts properties in all schemas alphabetically.
298 * @see https://redocly.com/docs/redoc/config/#sortpropsalphabetically
299 *
300 * @default false
301 */
302sortPropsAlphabetically: boolean;
303
304/**
305 * When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag.
306 * To sort operations alphabetically as well, you must set the sortOperationsAlphabetically setting to true.
307 * @see https://redocly.com/docs/redoc/config/#sorttagsalphabetically
308 *
309 * @requires sortOperationsAlphabetically true
310 * @default false
311 */
312sortTagsAlphabetically: boolean;
313
314/**
315 * If set to true, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
316 * @see https://redocly.com/docs/redoc/config/#untrusteddefinition
317 *
318 * @default false
319 */
320untrustedDefinition: boolean;
321
322/**
323 * Disables the Authorization panel that gets created by default
324 *
325 * @default false
326 */
327noAutoAuth: boolean;
328
329/**
330 * Suppress warnings
331 */
332suppressWarnings: boolean;
333
334/**
335 * Use the global prefix that is set via `app.setGlobalPrefix(...)`
336 */
337useGlobalPrefix: boolean;
338
339/**
340 * Defines one or multiple users that have access to the frontend
341 */
342auth: {
343
344    /**
345     * Enables the authentication for the frontend
346     * @default false
347     */
348    enabled: boolean;
349    
350    /**
351     * Array of usernames and passwords
352     */
353    users: Array<{ username: string, password: string }>;
354	
355};
356
357/**
358 * Defines the tagGroups
359 */
360tagGroups: Array<{
361
362    /**
363     * Name of the tagGroup
364     */
365    name: string;
366    
367    /**
368     * All tags that are assigned to this tagGroup
369     */
370    tags: string[];
371	
372}>;