@tsed/schema 8.0.0 → 8.0.2

package/src/decorators/operations/inFile.ts

@@ -0,0 +1,55 @@
+import {DecoratorParameters, Metadata, useDecorators, useMethodDecorators} from "@tsed/core";
+
+import {JsonParameterTypes} from "../../domain/JsonParameterTypes.js";
+import {Name} from "../common/name.js";
+import {Consumes} from "./consumes.js";
+import {In} from "./in.js";
+import {Returns} from "./returns.js";
+
+/**
+ * Add a input file parameter.
+ *
+ * ::: warning
+ * Don't use decorator with Ts.ED application to decorate parameters. Use @@BodyParams@@, @@PathParams@@, etc... instead.
+ * But you can use this decorator on Method, to add extra in parameters like Authorization header.
+ *
+ * ```typescript
+ * @Controller("/")
+ * class MyController {
+ *    @Post("/")
+ *    method(@InFile("file1") file: any) {
+ *    }
+ *  }
+ * ```
+ * :::
+ *
+ * @decorator
+ * @swagger
+ * @schema
+ * @input
+ * @operation
+ * @param name
+ */
+export function InFile(name: string): ParameterDecorator {
+  return (...args: DecoratorParameters): void => {
+    const [target, propertyKey, index] = args;
+    const multiple = Metadata.getParamTypes(target, propertyKey)[index as number] === Array;
+
+    name = (typeof name === "object" ? undefined : name)!;
+
+    const expression = [name, !multiple && "0"].filter(Boolean).join(".");
+
+    const decorators = useDecorators(
+      In(JsonParameterTypes.FILES),
+      Name(expression),
+      useMethodDecorators(
+        Returns(400).Description(
+          `<File too long | Too many parts | Too many files | Field name too long | Field value too long | Too many fields | Unexpected field>  [fieldName] Example: File too long file1`
+        ),
+        Consumes("multipart/form-data")
+      )
+    );
+
+    decorators(...args);
+  };
+}

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

@@ -0,0 +1,51 @@
+import {getSpec, Location, OperationPath, SpecTypes} from "../../index.js";
+
+describe("Location", () => {
+  it("should set Header", () => {
+    class MyController {
+      @(Location("/path/to/test", {description: "Path to next step"}).Status(301))
+      @OperationPath("GET", "/")
+      test() {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerTest",
+            parameters: [],
+            responses: {
+              "301": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                },
+                description: "Moved Permanently",
+                headers: {
+                  Location: {
+                    description: "Path to next step",
+                    example: "/path/to/test",
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/operations/location.ts

@@ -0,0 +1,26 @@
+import {JsonHeader} from "../../interfaces/JsonOpenSpec.js";
+import {Returns} from "./returns.js";
+
+/**
+ * Sets the response Location HTTP header to the specified path parameter.
+ *
+ * ```typescript
+ *  @Location('/foo/bar', {description: 'Location to the next step'})
+ *  @Location('http://example.com')
+ *  @Location('back')
+ *  private myMethod() {
+ *
+ *  }
+ * ```
+ *
+ * A path value of “back” has a special meaning, it refers to the URL specified in the `Referer` header of the request. If the `Referer` header was not specified, it refers to “/”.
+ *
+ * @param location
+ * @param meta
+ * @returns {Function}
+ * @decorator
+ * @operation
+ */
+export function Location(location: string, meta?: JsonHeader) {
+  return Returns().Location(location, meta);
+}

package/src/decorators/operations/operation.ts

@@ -0,0 +1,119 @@
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {DecoratorContext} from "../../domain/DecoratorContext.js";
+import {JsonMethodStore} from "../../domain/JsonMethodStore.js";
+import {mapOperationOptions} from "../../utils/mapOperationOptions.js";
+
+export interface RouteChainedDecorators {
+  <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
+
+  /**
+   * @param string
+   * @constructor
+   */
+  Path(string: string): this;
+
+  /**
+   * Set the operation method
+   * @param method
+   */
+  Method(method: OperationVerbs | string): this;
+
+  /**
+   * Set the operation id
+   * @param id
+   */
+  Id(id: string): this;
+
+  /**
+   * Set the operation id
+   * @param name
+   */
+  Name(name: string): this;
+
+  /**
+   *
+   * @param description
+   */
+  Description(description: string): this;
+
+  /**
+   * Summary
+   * @constructor
+   * @param Summary
+   */
+  Summary(Summary: string): this;
+
+  Use(...args: any[]): this;
+
+  UseAfter(...args: any[]): this;
+
+  UseBefore(...args: any[]): this;
+}
+
+class OperationDecoratorContext extends DecoratorContext<RouteChainedDecorators> {
+  readonly methods: string[] = ["name", "description", "summary", "method", "id", "use", "useAfter", "useBefore"];
+  protected declare entity: JsonMethodStore;
+
+  protected beforeInit() {
+    const path: string = this.get("path");
+    const method: string = OperationVerbs[this.get("method") as OperationVerbs] || OperationVerbs.CUSTOM;
+
+    path && this.entity.operation.addOperationPath(method, path);
+  }
+
+  protected onMapKey(key: string, value: any) {
+    switch (key) {
+      case "name":
+      case "id":
+        this.entity.operation.operationId(value);
+        return;
+      case "summary":
+        this.entity.operation.summary(value);
+        return;
+      case "description":
+        this.entity.operation.description(value);
+        return;
+      case "use":
+        this.entity.use(value);
+        return;
+      case "useAfter":
+        this.entity.after(value);
+        return;
+      case "useBefore":
+        this.entity.before(value);
+        return;
+    }
+
+    return super.onMapKey(key, value);
+  }
+}
+
+/**
+ * Describe a new route with a method and path.
+ *
+ * ```typescript
+ * @Controller('/')
+ * export class Ctrl {
+ *
+ *    @Route('GET', '/')
+ *    get() { }
+ * }
+ *
+ * ```
+ *
+ * @returns {Function}
+ * @param method
+ * @param path
+ * @param args
+ * @decorator
+ * @operation
+ */
+export function Operation(method: string, path: string, ...args: any[]): RouteChainedDecorators;
+export function Operation(...args: any[]): RouteChainedDecorators;
+export function Operation(...args: any[]): RouteChainedDecorators {
+  const routeOptions = mapOperationOptions(args);
+
+  const context = new OperationDecoratorContext(routeOptions);
+
+  return context.build();
+}

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

@@ -0,0 +1,43 @@
+import {getSpec, OperationId, OperationPath} from "../../index.js";
+
+describe("OperationId", () => {
+  it("should store metadata", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @OperationId("id")
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "id",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    let actualError: any;
+    try {
+      OperationId("id")(class Test {});
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("OperationId cannot be used as class decorator on Test");
+  });
+});

package/src/decorators/operations/operationId.ts

@@ -0,0 +1,22 @@
+import {DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Set a swagger operationId explicitly.
+ *
+ * @param operationId
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export function OperationId(operationId: string) {
+  return JsonEntityFn((store, args) => {
+    if (store.decoratorType !== DecoratorTypes.METHOD) {
+      throw new UnsupportedDecoratorType(OperationId, args);
+    }
+
+    store.operation!.operationId(operationId);
+  });
+}

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

@@ -0,0 +1,42 @@
+import {getSpec, OperationPath, OperationVerbs} from "../../index.js";
+
+describe("OperationPath", () => {
+  it("should store metadata", () => {
+    class MyController {
+      @OperationPath(OperationVerbs.OPTIONS, "/")
+      options() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          options: {
+            operationId: "myControllerOptions",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    let actualError: any;
+    try {
+      OperationPath("GET", "/")(class Test {});
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("OperationPath cannot be used as class decorator on Test");
+  });
+});

package/src/decorators/operations/operationPath.ts

@@ -0,0 +1,33 @@
+import {DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Declare new Operation with his path and http method.
+ *
+ * ::: warning
+ * Don't use decorator with Ts.ED application.
+ *
+ * Use theses decorators instead:
+ *
+ * <ApiList query="status.includes('decorator') && status.includes('httpMethod')" />
+ *
+ * :::
+ *
+ * @param method
+ * @param path
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export function OperationPath(method: OperationVerbs | string, path: string | RegExp = "/") {
+  return JsonEntityFn((store, args) => {
+    if (store.decoratorType !== DecoratorTypes.METHOD) {
+      throw new UnsupportedDecoratorType(OperationPath, args);
+    }
+
+    store.operation!.addOperationPath(method.toUpperCase(), path);
+  });
+}

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

@@ -0,0 +1,249 @@
+import {Ajv} from "ajv";
+
+import {
+  CollectionOf,
+  getJsonSchema,
+  getSpec,
+  Groups,
+  In,
+  OperationPath,
+  Path,
+  Property,
+  Required,
+  Returns,
+  SpecTypes
+} from "../../index.js";
+import {Partial} from "./partial.js";
+
+class ChildModel {
+  @Groups("!creation")
+  id: string;
+
+  @Required()
+  prop1: string;
+}
+
+class MyModel {
+  @Groups("!creation")
+  id: string;
+
+  @Groups("group.summary")
+  @Required()
+  prop1: string;
+
+  @Groups("group.extended")
+  @Required()
+  prop2: string;
+
+  @Property()
+  @Required()
+  prop3: string;
+
+  @CollectionOf(ChildModel)
+  prop4: ChildModel[];
+}
+
+describe("@Partial", () => {
+  describe("OpenSpec", () => {
+    it("should display fields when a group match with (OS3)", () => {
+      @Path("/")
+      class MyController {
+        @OperationPath("PATCH", "/")
+        @(Returns(200, MyModel).Groups("group.*"))
+        patch(@In("body") @Partial() payload: MyModel) {
+          return new MyModel();
+        }
+      }
+
+      const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+      expect(spec).toEqual({
+        components: {
+          schemas: {
+            ChildModel: {
+              properties: {
+                id: {
+                  type: "string"
+                },
+                prop1: {
+                  minLength: 1,
+                  type: "string"
+                }
+              },
+              required: ["prop1"],
+              type: "object"
+            },
+            MyModelPartial: {
+              properties: {
+                id: {
+                  type: "string"
+                },
+                prop3: {
+                  minLength: 1,
+                  type: "string"
+                },
+                prop4: {
+                  items: {
+                    $ref: "#/components/schemas/ChildModel"
+                  },
+                  type: "array"
+                }
+              },
+              type: "object"
+            },
+            MyModelGroup: {
+              properties: {
+                id: {
+                  type: "string"
+                },
+                prop1: {
+                  minLength: 1,
+                  type: "string"
+                },
+                prop2: {
+                  minLength: 1,
+                  type: "string"
+                },
+                prop3: {
+                  minLength: 1,
+                  type: "string"
+                },
+                prop4: {
+                  items: {
+                    $ref: "#/components/schemas/ChildModel"
+                  },
+                  type: "array"
+                }
+              },
+              required: ["prop1", "prop2", "prop3"],
+              type: "object"
+            }
+          }
+        },
+        paths: {
+          "/": {
+            patch: {
+              operationId: "myControllerPatch",
+              parameters: [],
+              requestBody: {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/MyModelPartial"
+                    }
+                  }
+                },
+                required: false
+              },
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: {
+                        $ref: "#/components/schemas/MyModelGroup"
+                      }
+                    }
+                  },
+                  description: "Success"
+                }
+              },
+              tags: ["MyController"]
+            }
+          }
+        },
+        tags: [
+          {
+            name: "MyController"
+          }
+        ]
+      });
+    });
+    it("should return a valid json-schema", () => {
+      const schema = getJsonSchema(MyModel, {});
+
+      expect(schema).toEqual({
+        definitions: {
+          ChildModel: {
+            properties: {
+              id: {
+                type: "string"
+              },
+              prop1: {
+                minLength: 1,
+                type: "string"
+              }
+            },
+            required: ["prop1"],
+            type: "object"
+          }
+        },
+        properties: {
+          id: {
+            type: "string"
+          },
+          prop3: {
+            minLength: 1,
+            type: "string"
+          },
+          prop4: {
+            items: {
+              $ref: "#/definitions/ChildModel"
+            },
+            type: "array"
+          }
+        },
+        required: ["prop3"],
+        type: "object"
+      });
+
+      const ajv = new Ajv({strict: true});
+
+      expect(ajv.validate(schema, {})).toBe(false);
+      expect(ajv.validate(schema, {prop3: "test"})).toBe(true);
+    });
+    it("should return a valid json-schema (partial)", () => {
+      const schema = getJsonSchema(MyModel, {
+        groups: ["partial"]
+      });
+
+      expect(schema).toEqual({
+        definitions: {
+          ChildModel: {
+            properties: {
+              id: {
+                type: "string"
+              },
+              prop1: {
+                minLength: 1,
+                type: "string"
+              }
+            },
+            required: ["prop1"],
+            type: "object"
+          }
+        },
+        properties: {
+          id: {
+            type: "string"
+          },
+          prop3: {
+            minLength: 1,
+            type: "string"
+          },
+          prop4: {
+            items: {
+              $ref: "#/definitions/ChildModel"
+            },
+            type: "array"
+          }
+        },
+        type: "object"
+      });
+
+      const ajv = new Ajv({strict: true});
+
+      expect(ajv.validate(schema, {})).toBe(true);
+      expect(ajv.validate(schema, {prop3: "test"})).toBe(true);
+    });
+  });
+});

package/src/decorators/operations/partial.ts

@@ -0,0 +1,14 @@
+import {Groups} from "../common/groups.js";
+
+/**
+ * Apply Partial group strategy on the input model
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Partial(): ParameterDecorator {
+  return Groups("partial") as any;
+}

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

@@ -0,0 +1,47 @@
+import {getSpec, OperationPath, Path} from "../../index.js";
+
+describe("Path", () => {
+  it("should declare a path", () => {
+    @Path("/path")
+    class MyController {
+      @OperationPath("POST", "/")
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/path": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    class Test {
+      test() {}
+    }
+
+    let actualError: any;
+    try {
+      Path("/")(Test.prototype, "test", 0);
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("Path cannot be used as parameter decorator on Test.test.[0]");
+  });
+});