📝 Improved documentation

Added table of properties, fixed some comments in redoc options interface
cosys-work · Jul 11, 2019 · de38c34 · de38c34
1 parent cea94c7
commit de38c34
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 19 deletions.
diff --git a/.github/.gitkeep b/.github/.gitkeep
diff --git a/README.md b/README.md
@@ -2,7 +2,6 @@
   NestJS-Redoc
   <h4 align="center">ReDoc powered frontend for your NestJS API spec</h4>
 </h1>
-<br />
 
 <div align="center">
   <a href="http://makeapullrequest.com">
@@ -14,29 +13,40 @@
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 </div>
 
-<p align="center">
-  <a href="#-features">Features</a> •
-  <a href="#-how-to-use">How to use</a> •
-  <a href="#-changelog">Changelog</a> •
-</p>
+<div align="center">
+
+[⚡ Features](#%E2%9A%A1-Features) | 
+[🗿 Installation](#%F0%9F%97%BF-Installation) |
+[❓ How to use](#%E2%9D%93-How-to-use) |
+[📜 Changelog](#%F0%9F%93%9C-Changelog) |
+[📋 ToDo](#%F0%9F%93%8B-ToDo)
+
+</div>
+
+<img src="./redoc.png"/>
 
 <p align="center">
-⚡ This is a ReDoc powered frontend for your NestJS API spec. By using ReDoc you improve your documentation presentation using a better UI/UX design
+
+📒 This is a [ReDoc](https://github.com/Redocly/redoc) powered frontend for your NestJS API spec.
+
 </p>
 
 ## ⚡ Features
 
-TBD
+* 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
+## 🗿 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, otherwise you may use a URL parameter for an OpenAPI definition instead of document object.
+You need to install the [Swagger Module](https://github.com/nestjs/swagger) 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
 
 ```typescript
 const options = new DocumentBuilder()
@@ -47,7 +57,7 @@ const options = new DocumentBuilder()
 const document = SwaggerModule.createDocument(app, options);
 ```
 
-Then add the followring example code.
+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 above.
 
@@ -67,6 +77,51 @@ const redocOptions: RedocOptions = {
 RedocModule.setup('/docs', app, document, redocOptions);
 ```
 
+## Available options
+
+### Redoc Options
+
+| Option                  | Description                                                                                                                                           | Type         | Note                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ |
+| title                   | Web site title (e.g: ReDoc documentation)                                                                                                             | 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      |
+
+**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 |
+
+## 📜 Changelog
+
+Bellow are a list of changes, some might go undocumented
+
+* 1.0.0 - First release
 
 ## 📋 ToDo
-bla bla
+
+* Add unit tests (i'm still learning how to)
+* Add Fastify support
+* Add the option to use a spec URL instead of document
diff --git a/redoc.png b/redoc.png
diff --git a/src/interfaces/redoc_options.interface.ts b/src/interfaces/redoc_options.interface.ts
@@ -20,7 +20,7 @@ export interface RedocOptions {
   requiredPropsFirst?: boolean;
   /** If set, propeties will be sorted alphabetically */
   sortPropsAlphabetically?: boolean;
-  /** If set the fields starting with "x-" will be showed, can be a boolean or a string with names of extensions to display */
+  /** If set the fields starting with "x-" will be shown, can be a boolean or a string with names of extensions to display */
   showExtensions?: boolean | string;
   /** If set, redoc won't inject authentication section automatically */
   noAutoAuth?: boolean;
@@ -32,9 +32,9 @@ export interface RedocOptions {
   nativeScrollbars?: boolean;
   /** This will hide the "Download spec" button, it only hides the button */
   hideDownloadButton?: boolean;
-  /** If set, the search bar will be disable */
+  /** If set, the search bar will be disabled */
   disableSearch?: boolean;
-  /** SHows only required fileds in request samples */
+  /** Shows only required fileds in request samples */
   onlyRequiredInSamples?: boolean;
 }
 

diff --git a/src/redoc-module.ts b/src/redoc-module.ts
@@ -5,7 +5,7 @@ import { Request, Response } from 'express';
 import { join } from 'path';
 import { LogoOptions, RedocDocument, RedocOptions } from './interfaces';
 import Joi = require('@hapi/joi');
-import exphbs = require('express-handlebars');
+import handlebars = require('express-handlebars');
 
 export class RedocModule {
 
@@ -32,7 +32,7 @@ export class RedocModule {
   }
 
   private static setupFastify() {
-    // throw new NotImplementedException('Fastify is not implemented yet');
+    throw new Error('Fastify is not implemented yet');
   }
 
   private static validateOptionsObject(options: RedocOptions, document: SwaggerDocument): Joi.ValidationResult<RedocOptions> {
@@ -75,7 +75,7 @@ export class RedocModule {
     const finalPath = this.normalizePath(path);
     // Serve swagger spec in another URL appended to the normalized path
     const swaggerDocUrl = join(finalPath, 'swagger.json');
-    const hbs = exphbs.create({
+    const hbs = handlebars.create({
       helpers: {
         toJSON: function (object: any) {
           return JSON.stringify(object);
@@ -120,7 +120,12 @@ export class RedocModule {
     return path.charAt(0) !== '/' ? '/' + path : path;
   }
 
-  private static addVendorExtensions(options: RedocOptions, document: RedocDocument) {
+  /**
+   * Add any vendor options if they are present in the options object
+   * @param options options object
+   * @param document redoc document
+   */
+  private static addVendorExtensions(options: RedocOptions, document: RedocDocument): RedocDocument {
     if (options.logo) {
       const logoOption: Partial<LogoOptions> = { ...options.logo };
       document.info['x-logo'] = logoOption;