Hypercolor Swagger Generator

Table of Contents

• Introduction
• Installation
• Prerequisites
  • Required Architecture
• Examples
  • Example Files
    • Example Root File
  • Types and Interfaces
• License
• More Information
  • Toolchain
  • Project Repository
  • Organization Repository

Introduction

This is a simple add-on for swagger-UI-Express that allows for programmatic generation of API documentation.

Installation

• NPM
  • npm i @hypercolor/swagger-generator
• Yarn
  • yarn add @hypercolor/swagger-generator

Prerequisites

• npm / yarn
• Node.js
• Express.js
• swagger.js file in the root of your project (see swagger.js example template file below)

module.exports = {
  openapi: "3.0.2",
  info: {
    title: '', //change_me
    description: '', //change_me

    version: "---"
  },
  servers: [],
  tags: [],
  paths: {},
  components: {
    securitySchemes: {
      ...
      // custom token validation descriptions here
    }
  }

}

Compatible API Routing Architecture Overview

• In order for the programmatic parsing of API routes and their associated documentation, routes need to be mounted into a specific format. Please visit the example section for more information and code examples.

Examples

Example Files:

Router Construction

export class ExpressRouter {
  constructor(private readonly options?: IRouterOptions) {
    this.options = options || {};
  }
  private formattedRoutes: Array<ExpressRoute> = [];
  public router: Router = Router();

  public get routes(): Array<IMountedRoute> {
    return this.formattedRoutes.map(formattedRoute => {
      return {
        path: formattedRoute.routePrefix,
        verb: formattedRoute.verb,
        controller: formattedRoute.controller
      };
    });
  }

  public static build(options: IRouterOptions, builder: (router: ExpressRouter) => void) {
    const router = new ExpressRouter(options);
    builder(router);
    return router;
  }

  public route(route: string) {
    const typedRoute = new ExpressRoute(route, this.router, this.options!);
    this.formattedRoutes.push(typedRoute);
    return typedRoute;
  }
}

Route Construction

export class ExpressRoute {
  constructor(public routePrefix: string, router: Router, private opts: IRouterOptions) {
    this.route = router.route(routePrefix);
  }
  public verb = 'unknown';
  public controller?: IControllerType;

  private route: IRoute;
  private myMiddleware: Array<RequestHandler> = [];


  public use(middleware: RequestHandler) {
    this.myMiddleware.push(middleware);
    return this;
  }
}

API Route Mounting File

export class V1ApiRoutes {
  public static buildAndMountRoutes(expressApp: e.Application, mountPoint: string) {
    const routers = [
      ExpressRouter.build({
        
      }, router => {
        router.route('hello').get(GetHelloController);
        router.route('welcome').get(GetWelcomeController);
      })
    ];
    
    routers.forEach(router => expressApp.use(mountPoint, router.router));
    
    return routers;
  }
}

Routes File

• Import @hypercolor/swagger-generator inside of wherever your routes are mounted at, and call the utility.
  • Be sure to give valid arguments for:
    • username
    • password
    • title
    • description

import {SwaggerGenerator} from '@hypercolor/swagger-generator';

export class ApiRoutes {
  public static register(app: e.Application) {
    const v1ApiRoutes: Array<ExpressRouter> = V1ApiRoutes.buildAndMountRoutes(app, '/api/v1');

    new SwaggerGenerator(
      "test_user",
      "change_me",
      "Title Here",
      "Create a useful description here",
    ).build(
      app,
      "/swagger/api/v1",
      v1ApiRoutes
    );
  }
}

Controller File

• Use the SwaggerDoc function as an annotation to assign the various expected formats for the specific API. The HC Swagg Util will use those during the compilation process.

import {SwaggerDoc} from '@hypercolor/swagger-generator';

@SwaggerDoc({
  description: '', //description of API
  body: {}, //Expected request body format,
  query: {}, //Expected request query format,
  params: {}, //Expected request params format
  response: {} //Expected response format 
})
export class ExampleController extends Controller {
  // controller logic here...
}

export abstract class Controller {
  constructor(protected request: Request, protected response: Response) {};
}

Types and Interfaces:

export type IControllerType = new (req: Request, res: Response, next: NextFunction) => any;

export interface IControllerDocumentation {
  summary?: string
  description?: string
  body?: {[key: string]: any}
  query?: {[key: string]: any}
  response?: {[key: string]: any}
}

export interface IMountedRoute {
  path: string,
  verb: string,
  controller: any
}

More Information

Toolchain

• Node.js
• TypeScript
• Express.js
• Swagger.js
• typedjson

Project Repository

Organization Repository