@tsed/schema 8.0.1 → 8.0.2

package/src/decorators/operations/route.spec.ts

@@ -0,0 +1,211 @@
+import {JsonEntityStore, OperationVerbs} from "../../index.js";
+import {All, Delete, Get, Head, Options, Patch, Post, Put} from "./route.js";
+
+describe("Route decorators", () => {
+  describe("All", () => {
+    it("should register route and middleware (1)", () => {
+      // WHEN
+      class Test {
+        @All("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.ALL,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+
+  describe("Get", () => {
+    it("should register route and middleware (1)", () => {
+      // WHEN
+      class Test {
+        @Get("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.GET,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+    it("should register route and middleware (2)", () => {
+      const middleware = () => {};
+
+      // WHEN
+      class Test {
+        @Get("/", middleware)
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.GET,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+    it("should register route and middleware (with handler)", () => {
+      const middleware = () => {};
+      const beforeMiddleware = () => {};
+      const afterMiddleware = () => {};
+
+      // WHEN
+      class Test {
+        @(Get("/").UseBefore(beforeMiddleware).Use(middleware).UseAfter(afterMiddleware))
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+      expect(endpoint.middlewares).toEqual([middleware]);
+      expect(endpoint.afterMiddlewares).toEqual([afterMiddleware]);
+      expect(endpoint.beforeMiddlewares).toEqual([beforeMiddleware]);
+    });
+  });
+
+  describe("Post", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @Post("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.POST,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+
+  describe("Put", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @(Put("/").Id("operationId").Summary("Summary").Description("Description"))
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.PUT,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+      expect(endpoint.operation!.get("description")).toBe("Description");
+      expect(endpoint.operation!.get("summary")).toBe("Summary");
+      expect(endpoint.operation!.get("operationId")).toBe("operationId");
+    });
+  });
+
+  describe("Delete", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @Delete("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.DELETE,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+
+  describe("Head", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @Head("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.HEAD,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+
+  describe("Patch", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @Patch("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.PATCH,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+
+  describe("Options", () => {
+    it("should register route and middleware", () => {
+      // WHEN
+      class Test {
+        @Options("/")
+        test() {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+      // THEN
+      expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.OPTIONS,
+          path: "/"
+        }
+      ]);
+      expect(endpoint.propertyKey).toBe("test");
+    });
+  });
+});

package/src/decorators/operations/route.ts

@@ -0,0 +1,154 @@
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {Operation} from "./operation.js";
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function All(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.ALL, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Get(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.GET, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Post(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.POST, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Put(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.PUT, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Delete(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.DELETE, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Head(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.HEAD, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Patch(path: string | RegExp | any = "/", ...args: any[]) {
+  return Operation(...[OperationVerbs.PATCH, path].concat(args));
+}
+
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export function Options(path: string | RegExp | unknown = "/", ...args: unknown[]) {
+  return Operation(...[OperationVerbs.OPTIONS, path].concat(args));
+}

package/src/decorators/operations/security.spec.ts

@@ -0,0 +1,162 @@
+import {getSpec, OperationPath, SpecTypes} from "../../index.js";
+import {Security} from "./security.js";
+
+describe("Security", () => {
+  it("should store metadata (method)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Security("oauth", "user")
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            security: [{oauth: ["user"]}],
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            security: [{oauth: ["user"]}],
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store multiple security schemes (method)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Security([{A: ["scope-1"]}, {B: [], C: ["scope-2", "scope-3"]}])
+      post() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerPost",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            security: [
+              {
+                A: ["scope-1"]
+              },
+              {
+                B: [],
+                C: ["scope-2", "scope-3"]
+              }
+            ],
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (class)", () => {
+    @Security("oauth", "user")
+    class MyController {
+      @OperationPath("GET", "/")
+      get() {}
+
+      @OperationPath("POST", "/")
+      @Security("oauth", "admin")
+      post() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            security: [
+              {
+                oauth: ["user"]
+              }
+            ],
+            tags: ["MyController"]
+          },
+          post: {
+            operationId: "myControllerPost",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            security: [
+              {
+                oauth: ["admin", "user"]
+              }
+            ],
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    class Test {
+      test() {}
+    }
+
+    let actualError: any;
+    try {
+      Security("POST", "/")(Test.prototype, "test", 0);
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("Security cannot be used as parameter decorator on Test.test.[0]");
+  });
+});

package/src/decorators/operations/security.ts

@@ -0,0 +1,83 @@
+import {decorateMethodsOf, DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+import {OpenSpecSecurity} from "@tsed/openspec";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add security metadata on the decorated method.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class ModelCtrl {
+ *    @Security("write:calendars")
+ *    async method() {}
+ * }
+ * ```
+ *
+ * @param name
+ * @param scopes
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export function Security(name: string, ...scopes: string[]): Function;
+/**
+ * Add security metadata on the decorated method.
+ *
+ * You can use it to add multiple authentication types.
+ * See <https://swagger.io/docs/specification/authentication/#multiple>.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class ModelCtrl {
+ *    @Security([{ "A": ["scope-1"] }, { "B": [], "C": ["scope-2", "scope-3"]}])
+ *    async method() {}
+ * }
+ * ```
+ * this will add the following security metadata
+ * ```yaml
+ * security: # A OR (B AND C)
+ *   - A: ["scope-1"]
+ *   - B: []
+ *     C: ["scope-2", "scope-3"]
+ * ```
+ *
+ * @param security
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export function Security(security: OpenSpecSecurity): Function;
+export function Security(nameOrSecurity: string | OpenSpecSecurity, ...scopes: string[]): Function {
+  return JsonEntityFn((store, args) => {
+    switch (store.decoratorType) {
+      case DecoratorTypes.METHOD:
+        if (Array.isArray(nameOrSecurity)) {
+          store.operation!.security(nameOrSecurity);
+        } else {
+          store.operation!.addSecurityScopes(nameOrSecurity, scopes);
+        }
+        break;
+      case DecoratorTypes.CLASS:
+        if (Array.isArray(nameOrSecurity)) {
+          decorateMethodsOf(args[0], Security(nameOrSecurity));
+        } else {
+          decorateMethodsOf(args[0], Security(nameOrSecurity, ...scopes));
+        }
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(Security, args);
+    }
+  });
+}