@tsed/openapi-utils 8.3.0

package/src/services/OpenAPIService.spec.ts

@@ -0,0 +1,35 @@
+import {writeFile} from "node:fs/promises";
+
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {OpenAPIService} from "../index.js";
+
+vi.mock("node:fs/promises");
+
+describe("SwaggerService", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+
+  describe("getOpenAPISpec()", () => {
+    it("should compile spec only once time", async () => {
+      const service = await PlatformTest.invoke<OpenAPIService>(OpenAPIService);
+      const result1 = await service.getOpenAPISpec({specVersion: "3.0.1"} as any);
+      const result2 = await service.getOpenAPISpec({specVersion: "3.0.1"} as any);
+
+      expect(result1).toEqual(result2);
+      expect(result1).toMatchSnapshot();
+    });
+  });
+
+  describe("writeOpenAPISpec()", () => {
+    it("should write spec only once time", async () => {
+      const service = await PlatformTest.invoke<OpenAPIService>(OpenAPIService);
+
+      await service.writeOpenAPISpec({specVersion: "3.0.1", outFile: "/path"} as any);
+
+      expect(writeFile).toHaveBeenCalledWith("/path", expect.any(String), {
+        encoding: "utf8"
+      });
+    });
+  });
+});

package/src/services/OpenAPIService.ts

@@ -0,0 +1,65 @@
+import {writeFile} from "node:fs/promises";
+
+import {Env, 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 {OpenAPI3Settings, OpenApiSettings, Swagger2Settings} from "../interfaces/OpenApiSettings.js";
+import {includeRoute} from "../utils/includeRoute.js";
+import {readSpec} from "../utils/readSpec.js";
+
+export class OpenAPIService {
+  protected platform = inject(Platform);
+
+  #specs: Map<string, OpenSpec3 | OpenSpec2> = new Map();
+
+  constructor() {}
+
+  /**
+   * Generate Spec for the given configuration
+   */
+  public async getOpenAPISpec(conf: OpenAPI3Settings): Promise<OpenSpec3>;
+  public async getOpenAPISpec(conf: Swagger2Settings): Promise<OpenSpec2>;
+  public async getOpenAPISpec(conf: OpenApiSettings): Promise<OpenSpec2>;
+  public async getOpenAPISpec(conf: OpenApiSettings) {
+    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);
+  }
+
+  async writeOpenAPISpec(conf: OpenApiSettings) {
+    const {outFile} = conf;
+    const env = constant<Env>("env");
+
+    if (env === Env.PROD || outFile) {
+      const spec = await this.getOpenAPISpec(conf);
+
+      if (outFile) {
+        return writeFile(outFile, JSON.stringify(spec, null, 2), {encoding: "utf8"});
+      }
+    }
+  }
+}
+
+injectable(OpenAPIService);

package/src/services/__snapshots__/OpenAPIService.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/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 {OpenApiSettings} from "../interfaces/OpenApiSettings.js";
+import {matchPath} from "./matchPath.js";
+
+export function includeRoute(route: string, provider: Provider, conf: OpenApiSettings): 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.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,15 @@
+export async function readSpec(path: string) {
+  const {readFile} = await import("node:fs/promises");
+  const {existsSync} = await import("node:fs");
+
+  if (existsSync(path)) {
+    try {
+      const response = await readFile(path, {encoding: "utf8"});
+
+      return JSON.parse(response);
+    } catch (e) {}
+  }
+
+  /* istanbul ignore next */
+  return {};
+}

package/vitest.config.mts

@@ -0,0 +1,21 @@
+// @ts-ignore
+import {presets} from "@tsed/vitest/presets";
+import {defineConfig} from "vitest/config";
+
+export default defineConfig(
+  {
+    ...presets,
+    test: {
+      ...presets.test,
+      coverage: {
+        ...presets.test.coverage,
+        thresholds: {
+          statements: 0,
+          branches: 0,
+          functions: 0,
+          lines: 0
+        }
+      }
+    }
+  }
+);