@whook/swagger-ui

A wrapper for the Whook HTTP Router to provide SwaggerUI for local dev

This module provides the GraphIQL UI to your local Whook server !

Usage

The DEV_MODE=1 environment variable must be used when starting your server (npm run dev does it by default).

Setup

Install the module:

npm i @whook/swagger-ui

To use it, just wrap the HTTP router with this module and override its registration with the Knifecycle instance inside the runServer function (usually in src/index.ts):

+ import initHTTPRouter from '@whook/http-router';
+ import wrapHTTPRouterWithSwaggerUI from '@whook/swagger-ui';

// (...)

// It is important to do this in the runServer function since it really
//  make sense only when actually running the server
export async function runServer(injectedNames = [], $ = new Knifecycle()) {

  // (...)

+   // Add support for Swagger UI by wrapping and
+  //  overriding the original HTTP Router
+   $.register(
+     wrapHTTPRouterWithSwaggerUI(initHTTPRouter),
+   );

  return await runBaseServer(injectedNames, $);
}

Declare this module types in your src/whook.d.ts type definitions:

+import type {
+   WhookSwaggerUIEnv,
+   WhookAPIOperationSwaggerConfig,
+   WhookSwaggerUIConfig,
+} from '@whook/swagger-ui';

// ...

declare module 'application-services' {

  export interface AppEnvVars
    extends BaseAppEnvVars,
      WhookBaseEnv,
      // (...)
+      WhookGraphIQLEnv,
      WhookSwaggerUIEnv {}

  // (...)

  export interface AppConfig
-    extends WhookBaseConfigs {}
+    extends WhookBaseConfigs, WhookSwaggerUIConfig {}

  // ...

  export interface WhookAPIHandlerDefinition<
    T extends Record<string, unknown> = Record<string, unknown>,
    U extends {
      [K in keyof U]: K extends `x-${string}` ? Record<string, unknown> : never;
    } = unknown,
    V extends Record<string, unknown> = Record<string, unknown>,
  > extends WhookBaseAPIHandlerDefinition<T, U> {
    operation: U & WhookAPIOperation<
        T &
+      WhookAPIOperationSwaggerConfig &
      WhookAPIOperationCORSConfig
    >;
  }

}

And add the SwaggerUI config (usually in src/config/common/config.js):

// ...
import type { AppConfig } from 'application-services';

const CONFIG: AppConfig = {
  // ...
  BASE_PATH: 'v4',
};


export default CONFIG;

API

Authors

• Nicolas Froidure

License

MIT