@tsed/swagger 8.0.1 → 8.0.2

package/package.json

@@ -2,13 +2,14 @@
   "name": "@tsed/swagger",
   "description": "Swagger package for Ts.ED framework",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.0.2",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -25,23 +26,23 @@
     "test:ci": "vitest run --coverage.thresholds.autoUpdate=true"
   },
   "dependencies": {
-    "@tsed/normalize-path": "8.0.1",
-    "@tsed/openspec": "8.0.1",
+    "@tsed/normalize-path": "8.0.2",
+    "@tsed/openspec": "8.0.2",
     "fs-extra": "11.2.0",
     "micromatch": "4.0.8",
     "swagger-ui-dist": ">=5.17.14",
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.1",
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/json-mapper": "8.0.1",
+    "@tsed/barrels": "8.0.2",
+    "@tsed/core": "8.0.2",
+    "@tsed/di": "8.0.2",
+    "@tsed/json-mapper": "8.0.2",
     "@tsed/monorepo-utils": "2.3.9",
-    "@tsed/openspec": "8.0.1",
-    "@tsed/platform-http": "8.0.1",
-    "@tsed/schema": "8.0.1",
-    "@tsed/typescript": "8.0.1",
+    "@tsed/openspec": "8.0.2",
+    "@tsed/platform-http": "8.0.2",
+    "@tsed/schema": "8.0.2",
+    "@tsed/typescript": "8.0.2",
     "@types/swagger-ui-dist": "3.30.5",
     "eslint": "9.12.0",
     "ts-node": "10.9.2",
@@ -49,7 +50,7 @@
     "vitest": "2.1.2"
   },
   "peerDependencies": {
-    "@tsed/platform-http": "8.0.1"
+    "@tsed/platform-http": "8.0.2"
   },
   "peerDependenciesMeta": {
     "@tsed/common": {

package/src/SwaggerModule.spec.ts

@@ -0,0 +1,64 @@
+import {logger} from "@tsed/di";
+import {application} from "@tsed/platform-http";
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {PlatformRouter} from "@tsed/platform-router";
+import Fs from "fs";
+import {absolutePath} from "swagger-ui-dist";
+
+import {SwaggerModule} from "./SwaggerModule.js";
+
+describe("SwaggerModule", () => {
+  beforeEach(() =>
+    PlatformTest.create({
+      httpPort: 8080,
+      httpsPort: 8081,
+      swagger: [
+        {
+          path: "/doc",
+          cssPath: "/cssPath",
+          jsPath: "/jsPath",
+          viewPath: "/viewsPath",
+          outFile: "/spec.json"
+        }
+      ]
+    })
+  );
+  afterEach(PlatformTest.reset);
+
+  describe("$onRoutesInit", () => {
+    it("should add middlewares", async () => {
+      const mod = await PlatformTest.invoke<SwaggerModule>(SwaggerModule);
+
+      vi.spyOn(application(), "get").mockReturnValue(undefined as never);
+      vi.spyOn(application(), "use").mockReturnValue(undefined as never);
+      vi.spyOn(PlatformRouter.prototype as any, "get").mockReturnValue(undefined);
+      vi.spyOn(PlatformRouter.prototype as any, "statics").mockReturnValue(undefined);
+
+      mod.$onRoutesInit();
+      mod.$onRoutesInit();
+
+      expect(application().use).toHaveBeenCalledWith("/doc", expect.any(Function));
+      expect(application().use).toHaveBeenCalledWith("/doc", expect.any(PlatformRouter));
+      expect(PlatformRouter.prototype.get).toHaveBeenCalledWith("/swagger.json", expect.any(Function));
+      expect(PlatformRouter.prototype.get).toHaveBeenCalledWith("/main.css", expect.any(Function));
+      expect(PlatformRouter.prototype.get).toHaveBeenCalledWith("/", expect.any(Function));
+      expect(PlatformRouter.prototype.statics).toHaveBeenCalledWith("/", {
+        root: absolutePath()
+      });
+    });
+  });
+
+  describe("$onReady", () => {
+    it("should display the right log", async () => {
+      const mod = await PlatformTest.invoke<SwaggerModule>(SwaggerModule);
+
+      vi.spyOn(Fs, "writeFile");
+      vi.spyOn(logger(), "info");
+
+      mod.$onReady();
+
+      expect(logger().info).toHaveBeenCalledWith("[default] Swagger JSON is available on https://0.0.0.0:8081/doc/swagger.json");
+      expect(logger().info).toHaveBeenCalledWith("[default] Swagger UI is available on https://0.0.0.0:8081/doc/");
+    });
+  });
+});

package/src/SwaggerModule.ts

@@ -0,0 +1,133 @@
+import Fs from "node:fs";
+import {join} from "node:path";
+
+import {Env} from "@tsed/core";
+import {configuration, constant, inject, injectable, logger, ProviderType} from "@tsed/di";
+import {normalizePath} from "@tsed/normalize-path";
+import {application, OnReady, OnRoutesInit, PlatformContext} from "@tsed/platform-http";
+import {PlatformRouter, useContextHandler} from "@tsed/platform-router";
+
+import {ROOT_DIR, SWAGGER_UI_DIST} from "./constants.js";
+import {SwaggerSettings} from "./interfaces/SwaggerSettings.js";
+import {cssMiddleware} from "./middlewares/cssMiddleware.js";
+import {indexMiddleware} from "./middlewares/indexMiddleware.js";
+import {jsMiddleware} from "./middlewares/jsMiddleware.js";
+import {redirectMiddleware} from "./middlewares/redirectMiddleware.js";
+import {SwaggerService} from "./services/SwaggerService.js";
+
+export class SwaggerModule implements OnRoutesInit, OnReady {
+  protected swaggerService = inject(SwaggerService);
+  protected env = constant<Env>("env");
+  protected disableRoutesSummary = constant<boolean>("logger.disableRoutesSummary");
+
+  private loaded = false;
+
+  get settings() {
+    return constant<SwaggerSettings[]>("swagger", []).filter((o) => !!o);
+  }
+
+  /**
+   *
+   */
+  $onRoutesInit() {
+    if (this.loaded) {
+      return;
+    }
+
+    const urls: any[] = this.getUrls();
+
+    this.settings.forEach((conf: SwaggerSettings) => {
+      const {path = "/"} = conf;
+
+      application().use(path, useContextHandler(redirectMiddleware(path)));
+      application().use(path, this.createRouter(conf, urls));
+    });
+
+    this.loaded = true;
+  }
+
+  $onReady() {
+    // istanbul ignore next
+    if (configuration().getBestHost && !this.disableRoutesSummary) {
+      const host = configuration().getBestHost();
+      const url = host.toString();
+
+      const displayLog = (conf: SwaggerSettings) => {
+        const {path = "/", fileName = "swagger.json", doc} = conf;
+
+        logger().info(`[${doc || "default"}] Swagger JSON is available on ${url}${normalizePath(path, fileName)}`);
+        logger().info(`[${doc || "default"}] Swagger UI is available on ${url}${path}/`);
+      };
+
+      this.settings.forEach((conf) => {
+        displayLog(conf);
+      });
+    }
+
+    this.generateSpecFiles();
+  }
+
+  generateSpecFiles() {
+    return Promise.all(
+      this.settings.map(async (conf) => {
+        const {outFile} = conf;
+
+        if (this.env === Env.PROD || outFile) {
+          const spec = await this.swaggerService.getOpenAPISpec(conf);
+
+          if (outFile) {
+            return Fs.writeFile(outFile, JSON.stringify(spec, null, 2), {encoding: "utf8"}, () => {});
+          }
+        }
+      })
+    );
+  }
+
+  private getUrls() {
+    return this.settings.reduce((acc: any[], conf) => {
+      const {path = "/", fileName = "swagger.json", doc, hidden} = conf;
+
+      if (!hidden) {
+        acc.push({url: normalizePath(path, fileName), name: doc || path});
+      }
+
+      return acc;
+    }, []);
+  }
+
+  /**
+   *
+   * @param conf
+   * @param urls
+   */
+  private createRouter(conf: SwaggerSettings, urls: string[]) {
+    const {disableSpec = false, fileName = "swagger.json", cssPath, jsPath, viewPath = join(ROOT_DIR, "../views/index.ejs")} = conf;
+    const router = new PlatformRouter();
+
+    if (!disableSpec) {
+      router.get(normalizePath("/", fileName), useContextHandler(this.middlewareSwaggerJson(conf)));
+    }
+    if (viewPath) {
+      if (cssPath) {
+        router.get("/main.css", useContextHandler(cssMiddleware(cssPath)));
+      }
+
+      if (jsPath) {
+        router.get("/main.js", useContextHandler(jsMiddleware(jsPath)));
+      }
+
+      router.get("/", useContextHandler(indexMiddleware(viewPath, {urls, ...conf})));
+      router.statics("/", {root: SWAGGER_UI_DIST});
+    }
+
+    return router;
+  }
+
+  private middlewareSwaggerJson(conf: SwaggerSettings) {
+    return async (ctx: PlatformContext) => {
+      ctx.response.status(200).body(await this.swaggerService.getOpenAPISpec(conf));
+    };
+  }
+}
+
+injectable(SwaggerModule).type(ProviderType.MODULE);

package/src/constants.ts

@@ -0,0 +1,4 @@
+import getAbsoluteFSPath from "swagger-ui-dist/absolute-path.js";
+
+export const SWAGGER_UI_DIST = getAbsoluteFSPath();
+export const ROOT_DIR = import.meta.dirname;

package/src/decorators/docs.ts

@@ -0,0 +1,14 @@
+import {StoreMerge} from "@tsed/core";
+
+/**
+ * Set the type documentation for this class.
+ *
+ * See [swagger documentation](/tutorials/swagger.html)
+ *
+ * @decorator
+ * @swagger
+ * @param docs
+ */
+export function Docs(...docs: string[]) {
+  return StoreMerge("docs", docs);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./constants.js";
+export * from "./decorators/docs.js";
+export * from "./interfaces/interfaces.js";
+export * from "./interfaces/SwaggerSettings.js";
+export * from "./middlewares/cssMiddleware.js";
+export * from "./middlewares/indexMiddleware.js";
+export * from "./middlewares/jsMiddleware.js";
+export * from "./middlewares/redirectMiddleware.js";
+export * from "./services/SwaggerService.js";
+export * from "./SwaggerModule.js";
+export * from "./utils/includeRoute.js";
+export * from "./utils/matchPath.js";
+export * from "./utils/readSpec.js";

package/src/interfaces/SwaggerSettings.ts

@@ -0,0 +1,102 @@
+import {OpenSpec2, OpenSpec3, OpenSpecVersions, OS2Versions, OS3Versions} from "@tsed/openspec";
+
+export interface SwaggerUIOptions {
+  configUrl?: string;
+  url?: string;
+  urls?: {url: string; name: string; primaryName?: string}[];
+  layout?: string;
+  validatorUrl?: string;
+  oauth?: any;
+  authorize?: any;
+
+  [key: string]: any;
+}
+
+export interface SwaggerSettingsBase {
+  /**
+   * The url subpath to access to the documentation.
+   */
+  path: string;
+  /**
+   * Specify the spec version you want to generate.
+   */
+  specVersion?: OpenSpecVersions;
+  /**
+   * Swagger file name. By default swagger.json
+   */
+  fileName?: string;
+  /**
+   * Hidden documentation. Use this to hide documentation link in the dropdown.
+   */
+  hidden?: string;
+  /**
+   * The documentation key used by `@Docs` decorator to create several swagger documentations.
+   */
+  doc?: string;
+  /**
+   * The path to the CSS file.
+   */
+  cssPath?: string;
+  /**
+   * The path to the JS file.
+   */
+  jsPath?: string;
+  /**
+   * The path to the ejs file to create html page.
+   */
+  viewPath?: string | false;
+  /**
+   * SwaggerUI options. See (https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md)
+   */
+  options?: SwaggerUIOptions;
+  /**
+   * Display the search field in the navbar.
+   */
+  showExplorer?: boolean;
+  /**
+   * Load the base spec documentation from the specified path.
+   */
+  specPath?: string;
+  /**
+   * Write the `swagger.json` spec documentation on the specified path.
+   */
+  outFile?: string;
+  /**
+   * Sort paths by alphabetical order
+   */
+  sortPaths?: boolean;
+  /**
+   * A function to generate the operationId.
+   */
+  operationIdFormatter?: (name: string, propertyKey: string, path: string) => string;
+  /**
+   * A pattern to generate the operationId. Format of operationId field (%c: class name, %m: method name).
+   */
+  operationIdPattern?: string;
+  /**
+   *
+   */
+  disableSpec?: boolean;
+  /**
+   * Include only controllers whose paths match the pattern list provided.
+   */
+  pathPatterns?: string[];
+}
+
+export interface SwaggerOS2Settings extends SwaggerSettingsBase {
+  specVersion?: OS2Versions;
+  /**
+   * OpenSpec 2
+   */
+  spec?: Partial<OpenSpec2>;
+}
+
+export interface SwaggerOS3Settings extends SwaggerSettingsBase {
+  specVersion?: OS3Versions;
+  /**
+   * OpenSpec 3
+   */
+  spec?: Partial<OpenSpec3>;
+}
+
+export type SwaggerSettings = SwaggerOS2Settings | SwaggerOS3Settings;

package/src/interfaces/interfaces.ts

@@ -0,0 +1,9 @@
+import {SwaggerSettings} from "./SwaggerSettings.js";
+
+declare global {
+  namespace TsED {
+    interface Configuration {
+      swagger: SwaggerSettings[];
+    }
+  }
+}

package/src/middlewares/cssMiddleware.spec.ts

@@ -0,0 +1,24 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+import Fs from "fs";
+
+import {cssMiddleware} from "./cssMiddleware.js";
+
+describe("cssMiddleware", () => {
+  beforeEach(PlatformTest.create);
+  afterEach(PlatformTest.reset);
+  beforeEach(() => {
+    vi.spyOn(Fs, "readFileSync").mockReturnValue(".css{}");
+  });
+  it("should create a middleware", () => {
+    const ctx = PlatformTest.createRequestContext();
+
+    cssMiddleware("/path")(ctx);
+
+    expect(ctx.response.raw.headers).toEqual({
+      "content-type": "text/css",
+      "x-request-id": "id"
+    });
+    expect(ctx.response.raw.statusCode).toEqual(200);
+    expect(ctx.response.raw.data).toEqual(".css{}");
+  });
+});

package/src/middlewares/cssMiddleware.ts

@@ -0,0 +1,19 @@
+import {PlatformContext} from "@tsed/platform-http";
+import Fs from "fs";
+import {resolve} from "path";
+
+/**
+ * @ignore
+ * @param path
+ */
+export function cssMiddleware(path: string) {
+  return (ctx: PlatformContext) => {
+    const content = Fs.readFileSync(resolve(path), {encoding: "utf8"});
+    ctx.response
+      .setHeaders({
+        "Content-Type": "text/css"
+      })
+      .status(200)
+      .body(content);
+  };
+}

package/src/middlewares/indexMiddleware.spec.ts

@@ -0,0 +1,34 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {indexMiddleware} from "./indexMiddleware.js";
+
+describe("indexMiddleware and redirect", () => {
+  beforeEach(PlatformTest.create);
+  afterEach(PlatformTest.reset);
+  it("should create a middleware", async () => {
+    const ctx = PlatformTest.createRequestContext();
+    vi.spyOn(ctx.response, "render").mockResolvedValue("");
+
+    const viewPath = "/swagger.ejs";
+    const conf = {
+      path: "/doc",
+      options: {},
+      showExplorer: false,
+      cssPath: "/path.css",
+      jsPath: "/path.js",
+      urls: []
+    };
+
+    await indexMiddleware(viewPath, conf)(ctx);
+
+    expect(ctx.response.render).toHaveBeenCalledWith(viewPath, {
+      spec: {},
+      cssPath: "/path.css",
+      jsPath: "/path.js",
+      showExplorer: false,
+      swaggerOptions: {},
+      url: "/doc/swagger.json",
+      urls: []
+    });
+  });
+});

package/src/middlewares/indexMiddleware.ts

@@ -0,0 +1,26 @@
+import {PlatformContext} from "@tsed/platform-http";
+
+import {SwaggerSettings} from "../interfaces/SwaggerSettings.js";
+
+/**
+ * @ignore
+ * @param viewPath
+ * @param conf
+ */
+export function indexMiddleware(viewPath: string, conf: SwaggerSettings & {urls: string[]}) {
+  return async (ctx: PlatformContext) => {
+    const {path = "/", options = {}, showExplorer, cssPath, jsPath, urls} = conf;
+
+    ctx.response.body(
+      await ctx.response.render(viewPath, {
+        spec: {},
+        url: `${path}/swagger.json`,
+        urls,
+        showExplorer,
+        cssPath,
+        jsPath,
+        swaggerOptions: options
+      })
+    );
+  };
+}

package/src/middlewares/jsMiddleware.spec.ts

@@ -0,0 +1,24 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+import Fs from "fs";
+
+import {jsMiddleware} from "./jsMiddleware.js";
+
+describe("jsMiddleware", () => {
+  beforeEach(PlatformTest.create);
+  afterEach(PlatformTest.reset);
+  beforeEach(() => {
+    vi.spyOn(Fs, "readFileSync").mockReturnValue("var test=1");
+  });
+  it("should create a middleware", () => {
+    const ctx = PlatformTest.createRequestContext();
+
+    jsMiddleware("/path")(ctx);
+
+    expect(ctx.response.raw.headers).toEqual({
+      "content-type": "application/javascript",
+      "x-request-id": "id"
+    });
+    expect(ctx.response.raw.statusCode).toBe(200);
+    expect(ctx.response.raw.data).toBe("var test=1");
+  });
+});

package/src/middlewares/jsMiddleware.ts

@@ -0,0 +1,14 @@
+import {PlatformContext} from "@tsed/platform-http";
+import Fs from "fs";
+import {resolve} from "path";
+
+/**
+ * @ignore
+ * @param path
+ */
+export function jsMiddleware(path: string) {
+  return (ctx: PlatformContext) => {
+    const content = Fs.readFileSync(resolve(path), {encoding: "utf8"});
+    ctx.response.setHeaders({"Content-Type": "application/javascript"}).status(200).body(content);
+  };
+}

package/src/middlewares/redirectMiddleware.spec.ts

@@ -0,0 +1,31 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {redirectMiddleware} from "./redirectMiddleware.js";
+
+describe("redirectMiddleware and redirect", () => {
+  beforeEach(PlatformTest.create);
+  afterEach(PlatformTest.reset);
+  it("should create a middleware", () => {
+    const ctx = PlatformTest.createRequestContext();
+    vi.spyOn(ctx.response, "redirect").mockReturnValue(undefined as never);
+
+    ctx.request.raw.url = "/path";
+    ctx.request.raw.originalUrl = "/path";
+    ctx.request.raw.method = "GET";
+
+    redirectMiddleware("/path")(ctx);
+
+    expect(ctx.response.redirect).toHaveBeenCalledWith(302, "/path/");
+  });
+  it("should create a middleware and call next", () => {
+    const ctx = PlatformTest.createRequestContext();
+    vi.spyOn(ctx.response, "redirect");
+    ctx.request.raw.url = "/path/";
+    ctx.request.raw.method = "GET";
+    ctx.request.raw.originalUrl = "/path/";
+
+    redirectMiddleware("/path")(ctx);
+
+    expect(ctx.response.redirect).not.toHaveBeenCalled();
+  });
+});

package/src/middlewares/redirectMiddleware.ts

@@ -0,0 +1,13 @@
+import {PlatformContext} from "@tsed/platform-http";
+
+/**
+ * @ignore
+ * @param path
+ */
+export function redirectMiddleware(path: string) {
+  return (ctx: PlatformContext) => {
+    if (ctx.request.method?.toUpperCase() === "GET" && ctx.request.url === path && !ctx.request.url.match(/\/$/)) {
+      ctx.response.redirect(302, `${path}/`);
+    }
+  };
+}

package/src/services/SwaggerService.spec.ts

@@ -0,0 +1,19 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {SwaggerService} from "../index.js";
+
+describe("SwaggerService", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+
+  describe("getOpenAPISpec()", () => {
+    it("should compile spec only once time", async () => {
+      const swaggerService = await PlatformTest.invoke<SwaggerService>(SwaggerService);
+      const result1 = await swaggerService.getOpenAPISpec({specVersion: "3.0.1"} as any);
+      const result2 = await swaggerService.getOpenAPISpec({specVersion: "3.0.1"} as any);
+
+      expect(result1).toEqual(result2);
+      expect(result1).toMatchSnapshot();
+    });
+  });
+});

package/src/services/SwaggerService.ts

@@ -0,0 +1,51 @@
+import type {Type} from "@tsed/core";
+import {constant, inject, injectable} from "@tsed/di";
+import {OpenSpec2, OpenSpec3} from "@tsed/openspec";
+import {Platform} from "@tsed/platform-http";
+import {generateSpec} from "@tsed/schema";
+
+import {SwaggerOS2Settings, SwaggerOS3Settings, SwaggerSettings} from "../interfaces/SwaggerSettings.js";
+import {includeRoute} from "../utils/includeRoute.js";
+import {readSpec} from "../utils/readSpec.js";
+
+export class SwaggerService {
+  protected platform = inject(Platform);
+
+  #specs: Map<string, OpenSpec3 | OpenSpec2> = new Map();
+
+  constructor() {}
+
+  /**
+   * Generate Spec for the given configuration
+   * @returns {Spec}
+   */
+  public async getOpenAPISpec(conf: SwaggerOS3Settings): Promise<OpenSpec3>;
+  public async getOpenAPISpec(conf: SwaggerOS2Settings): Promise<OpenSpec2>;
+  public async getOpenAPISpec(conf: SwaggerSettings): Promise<OpenSpec2>;
+  public async getOpenAPISpec(conf: SwaggerSettings) {
+    if (!this.#specs.has(conf.path)) {
+      const version = constant("version", "1.0.0");
+      const acceptMimes = constant<string>("acceptMimes");
+      const specPath = conf.specPath;
+
+      const tokens = this.platform
+        .getMountedControllers()
+        .filter(({routes, provider}) => [...routes.values()].some((route) => includeRoute(route, provider, conf)))
+        .map(({route, provider}) => ({token: provider.token as Type, rootPath: route}));
+
+      const spec = generateSpec({
+        tokens,
+        ...conf,
+        fileSpec: specPath ? await readSpec(specPath) : {},
+        version,
+        acceptMimes
+      });
+
+      this.#specs.set(conf.path, spec);
+    }
+
+    return this.#specs.get(conf.path);
+  }
+}
+
+injectable(SwaggerService);

package/src/services/__snapshots__/SwaggerService.spec.ts.snap

@@ -0,0 +1,11 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`SwaggerService > getOpenAPISpec() > should compile spec only once time 1`] = `
+{
+  "info": {
+    "title": "Api documentation",
+    "version": "1.0.0",
+  },
+  "openapi": "3.0.1",
+}
+`;

package/src/utils/includeRoute.spec.ts

@@ -0,0 +1,111 @@
+import {ControllerProvider} from "@tsed/di";
+import {Hidden} from "@tsed/schema";
+
+import {Docs} from "../decorators/docs.js";
+import {includeRoute} from "./includeRoute.js";
+
+@Hidden()
+class HiddenCtrl {}
+
+@Docs("test")
+class DocsCtrl {}
+
+class PlainCtrl {}
+
+describe("includeRoute", () => {
+  it.each([
+    {
+      label: "a simple configuration + HiddenCtrl are given",
+      expected: false,
+      route: "/test",
+      conf: {
+        path: "/swagger"
+      },
+      controller: HiddenCtrl
+    },
+    {
+      label: "a simple configuration + PlainCtrl are given",
+      expected: true,
+      route: "/test",
+      conf: {
+        path: "/swagger"
+      },
+      controller: PlainCtrl
+    },
+    {
+      label: "a given configuration with doc property doesn't match route",
+      expected: false,
+      route: "/test",
+      conf: {
+        path: "/swagger",
+        doc: "notmatch"
+      },
+      controller: DocsCtrl
+    },
+    {
+      label: "a given configuration with doc property matching route",
+      expected: true,
+      route: "/test",
+      conf: {
+        path: "/swagger",
+        doc: "test"
+      },
+      controller: DocsCtrl
+    },
+    {
+      label: "a given configuration with pathPatterns property matching route",
+      expected: true,
+      route: "/should/match",
+      conf: {
+        path: "/swagger",
+        pathPatterns: ["/should/**"]
+      },
+      controller: PlainCtrl
+    },
+    {
+      label: "a given configuration with pathPatterns property doesn't match route",
+      expected: false,
+      route: "/shouldnot/match",
+      conf: {
+        path: "/swagger",
+        pathPatterns: ["/notmatch/**"]
+      },
+      controller: PlainCtrl
+    },
+    {
+      label: "a given configuration with pathPatterns property doesn't match route - negation on pathPatterns",
+      expected: false,
+      route: "/should/match",
+      conf: {
+        path: "/swagger",
+        pathPatterns: ["!/should/**"]
+      },
+      controller: PlainCtrl
+    },
+    {
+      label: "a given configuration with pathPatterns/doc properties but only doc match",
+      expected: true,
+      route: "/shouldnot/match",
+      conf: {
+        path: "/swagger",
+        doc: "test",
+        pathPatterns: ["/notmatch/**"]
+      },
+      controller: DocsCtrl
+    },
+    {
+      label: "a given configuration with pathPatterns/doc properties but only pathPattern match",
+      expected: true,
+      route: "/should/match",
+      conf: {
+        path: "/swagger",
+        doc: "nomatch",
+        pathPatterns: ["/should/**"]
+      },
+      controller: DocsCtrl
+    }
+  ])("should return $expected when $label ($route)", ({expected, conf, route, controller}) => {
+    const provider = new ControllerProvider(controller);
+    expect(includeRoute(route, provider, conf as any)).toBe(expected);
+  });
+});

package/src/utils/includeRoute.ts

@@ -0,0 +1,22 @@
+import {Provider} from "@tsed/di";
+
+import {SwaggerSettings} from "../interfaces/SwaggerSettings.js";
+import {matchPath} from "./matchPath.js";
+
+export function includeRoute(route: string, provider: Provider, conf: SwaggerSettings): boolean {
+  const hidden = provider.store.get("hidden");
+  const docs = provider.store.get("docs") || [];
+  const {doc, pathPatterns} = conf;
+  const inDoc = doc && docs.indexOf(doc) > -1;
+  const pathPatternMatch = pathPatterns && matchPath(route, pathPatterns);
+
+  if (hidden) {
+    return false;
+  }
+
+  if (!doc && !pathPatterns) {
+    return true;
+  }
+
+  return !!(inDoc || pathPatternMatch);
+}

package/src/utils/matchPath.spec.ts

@@ -0,0 +1,16 @@
+import {matchPath} from "./matchPath.js";
+
+describe("matchPath", () => {
+  it("should match route with the glob pattern", () => {
+    expect(matchPath("/user", ["/user/**"])).toBe(true);
+    expect(matchPath("/user", [])).toBe(true);
+    expect(matchPath("/user")).toBe(true);
+    expect(matchPath("/test", ["!/user/**"])).toBe(true);
+  });
+
+  it("should not match route with the glob pattern", () => {
+    const result = matchPath("/test", ["/user/**"]);
+
+    expect(result).toBe(false);
+  });
+});

package/src/utils/matchPath.ts

@@ -0,0 +1,5 @@
+import micromatch from "micromatch";
+
+export function matchPath(path: string, patterns?: string[]) {
+  return patterns && patterns.length ? micromatch.isMatch(path, patterns) : true;
+}

package/src/utils/readSpec.ts

@@ -0,0 +1,11 @@
+export async function readSpec(path: string) {
+  const {default: fs} = await import("fs-extra");
+  if (fs.existsSync(path)) {
+    try {
+      return await fs.readJSON(path, {encoding: "utf8"});
+    } catch (e) {}
+  }
+
+  /* istanbul ignore next */
+  return {};
+}