@tsed/schema 8.0.1 → 8.0.3

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

@@ -0,0 +1,321 @@
+import {execMapper, getSpec, In, JsonEntityStore, Name, number, OperationPath, Path, SpecTypes} from "../../index.js";
+
+describe("In", () => {
+  it("should declare all schema correctly (param)", () => {
+    // WHEN
+    class Controller {
+      method(@In("path") @Name("basic") basic: string) {}
+    }
+
+    // THEN
+    getSpec(Controller, {
+      specType: SpecTypes.SWAGGER
+    });
+
+    const paramSchema = JsonEntityStore.from(Controller, "method", 0);
+    const methodSchema = paramSchema.parent;
+    const operation = execMapper("operation", [methodSchema.operation], {});
+
+    expect(operation).toEqual({
+      parameters: [
+        {
+          in: "path",
+          name: "basic",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        }
+      ],
+      responses: {
+        "200": {
+          description: "Success"
+        }
+      }
+    });
+  });
+  it("should declare all schema correctly (method)", () => {
+    // WHEN
+    class Controller {
+      @(In("header").Type(String).Name("Authorization").Required().Description("description"))
+      method(@In("path") @Name("basic") basic: string) {}
+    }
+
+    // THEN
+    getSpec(Controller, {
+      specType: SpecTypes.SWAGGER
+    });
+
+    const paramSchema = JsonEntityStore.from(Controller, "method", 0);
+    const methodSchema = paramSchema.parent;
+    const operation = execMapper("operation", [methodSchema.operation], {});
+
+    expect(operation).toEqual({
+      parameters: [
+        {
+          in: "path",
+          name: "basic",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        },
+        {
+          description: "description",
+          in: "header",
+          name: "Authorization",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        }
+      ],
+      responses: {
+        "200": {
+          description: "Success"
+        }
+      }
+    });
+  });
+  it("should declare all schema correctly (class)", () => {
+    // WHEN
+    class Controller {
+      @(In("header").Type(String).Name("Authorization").Required().Description("description"))
+      method(@In("path") @Name("basic") basic: string) {}
+    }
+
+    // THEN
+    getSpec(Controller, {
+      specType: SpecTypes.SWAGGER
+    });
+
+    const paramSchema = JsonEntityStore.from(Controller, "method", 0);
+    const methodSchema = paramSchema.parent;
+    const operation = execMapper("operation", [methodSchema.operation], {});
+
+    expect(operation).toEqual({
+      parameters: [
+        {
+          in: "path",
+          name: "basic",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        },
+        {
+          description: "description",
+          in: "header",
+          name: "Authorization",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        }
+      ],
+      responses: {
+        "200": {
+          description: "Success"
+        }
+      }
+    });
+  });
+  it("should declare a pattern", () => {
+    // WHEN
+    @Path("/:parentId")
+    @(In("path")
+      .Type(String)
+      .Name("parentId")
+      .Required()
+      .Description("description")
+      .Pattern(/^[0-9a-fA-F]{24}$/))
+    class Controller {
+      @OperationPath("GET", "/:path")
+      method(@In("path") @Name("basic") basic: string) {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller, {
+      specType: SpecTypes.OPENAPI
+    });
+
+    const paramSchema = JsonEntityStore.from(Controller, "method", 0);
+    const methodSchema = paramSchema.parent;
+    const operation = execMapper("operation", [methodSchema.operation!], {
+      specType: SpecTypes.OPENAPI
+    });
+
+    expect(operation).toEqual({
+      parameters: [
+        {
+          in: "path",
+          name: "basic",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        },
+        {
+          description: "description",
+          in: "path",
+          name: "parentId",
+          required: true,
+          schema: {
+            pattern: "^[0-9a-fA-F]{24}$",
+            type: "string"
+          }
+        }
+      ],
+      responses: {
+        "200": {
+          description: "Success"
+        }
+      }
+    });
+    expect(spec).toEqual({
+      paths: {
+        "/{parentId}/{path}": {
+          get: {
+            operationId: "controllerMethod",
+            parameters: [
+              {
+                description: "description",
+                in: "path",
+                name: "parentId",
+                required: true,
+                schema: {
+                  type: "string",
+                  pattern: "^[0-9a-fA-F]{24}$"
+                }
+              },
+              {
+                in: "path",
+                name: "path",
+                required: true,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare schema", () => {
+    // WHEN
+    @Path("/:parentId")
+    @(In("path").Name("parentId").Required().Description("description").Schema(number().integer().minimum(2)))
+    class Controller {
+      @OperationPath("GET", "/:path")
+      method(@In("path") @Name("basic") basic: string) {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller, {
+      specType: SpecTypes.OPENAPI
+    });
+
+    const paramSchema = JsonEntityStore.from(Controller, "method", 0);
+    const methodSchema = paramSchema.parent;
+    const operation = execMapper("operation", [methodSchema.operation!], {
+      specType: SpecTypes.OPENAPI
+    });
+
+    expect(operation).toEqual({
+      parameters: [
+        {
+          in: "path",
+          name: "basic",
+          required: true,
+          schema: {
+            type: "string"
+          }
+        },
+        {
+          description: "description",
+          in: "path",
+          name: "parentId",
+          required: true,
+          schema: {
+            minimum: 2,
+            multipleOf: 1,
+            type: "integer"
+          }
+        }
+      ],
+      responses: {
+        "200": {
+          description: "Success"
+        }
+      }
+    });
+    expect(spec).toEqual({
+      paths: {
+        "/{parentId}/{path}": {
+          get: {
+            operationId: "controllerMethod",
+            parameters: [
+              {
+                description: "description",
+                in: "path",
+                name: "parentId",
+                required: true,
+                schema: {
+                  minimum: 2,
+                  multipleOf: 1,
+                  type: "integer"
+                }
+              },
+              {
+                in: "path",
+                name: "path",
+                required: true,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    class Test {
+      test() {}
+    }
+
+    let actualError: any;
+    try {
+      // @ts-ignore
+      In("tags")(Test.prototype, "test");
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("In cannot be used as property decorator on Test.test");
+  });
+});

package/src/decorators/operations/in.ts

@@ -0,0 +1,141 @@
+import {decorateMethodsOf, DecoratorTypes, Type, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {JsonMethodStore} from "../../domain/JsonMethodStore.js";
+import {JsonParameter} from "../../domain/JsonParameter.js";
+import {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonParameterTypes} from "../../domain/JsonParameterTypes.js";
+import {JsonSchema, JsonSchemaObject} from "../../domain/JsonSchema.js";
+
+export interface InChainedDecorators {
+  <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
+
+  (target: Object, propertyKey: string | symbol, parameterIndex: number): void;
+
+  (target: Function): void;
+
+  /**
+   * Type of this in parameter
+   * @param type
+   */
+  Type(type: Type<any>): this;
+
+  /**
+   *
+   * @param name
+   */
+  Name(name: string): this;
+
+  /**
+   *
+   * @param description
+   */
+  Description(description: string): this;
+
+  /**
+   *
+   * @param required
+   */
+  Required(required?: boolean): this;
+
+  /**
+   * Add pattern constraint. Only available for OPENAPI.
+   * @param pattern
+   */
+  Pattern(pattern: string | RegExp): this;
+
+  /**
+   * Add custom schema.
+   * @param schema
+   */
+  Schema(schema: Partial<JsonSchemaObject | JsonSchema>): this;
+}
+
+/**
+ * Add a input 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 {
+ *    @Get("/")
+ *    @In("header").Type(String).Name("Authorization").Required()
+ *    method() {
+ *    }
+ *  }
+ * ```
+ * :::
+ *
+ * @param inType
+ * @decorator
+ * @swagger
+ * @schema
+ * @input
+ * @operation
+ */
+export function In(inType: JsonParameterTypes | string): InChainedDecorators {
+  const jsonParameter = new JsonParameter();
+  const schema: any = {};
+
+  const decorator = (target: any, propertyKey?: string | symbol, index?: PropertyDescriptor | number) => {
+    const store = JsonEntityStore.from(target, propertyKey, index);
+
+    switch (store.decoratorType) {
+      case DecoratorTypes.PARAM:
+        (store as JsonParameterStore).parameter.in(inType);
+        break;
+      case DecoratorTypes.METHOD:
+        jsonParameter.in(inType);
+        (store as JsonMethodStore).operation.addParameter(-1, jsonParameter);
+
+        jsonParameter.schema(JsonSchema.from(schema));
+        break;
+
+      case DecoratorTypes.CLASS:
+        decorateMethodsOf(target, decorator);
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(In, [target, propertyKey, index]);
+    }
+  };
+
+  decorator.Type = (type: Type<any>) => {
+    schema.type = type;
+
+    return decorator;
+  };
+
+  decorator.Name = (name: string) => {
+    jsonParameter.name(name);
+
+    return decorator;
+  };
+
+  decorator.Description = (description: string) => {
+    jsonParameter.description(description);
+
+    return decorator;
+  };
+
+  decorator.Required = (required: boolean = true) => {
+    jsonParameter.required(required);
+
+    return decorator;
+  };
+
+  decorator.Pattern = (pattern: string | RegExp) => {
+    return decorator.Schema({pattern: pattern.toString()});
+  };
+
+  decorator.Schema = (_schema: any) => {
+    Object.assign(schema, _schema.toJSON ? _schema.toJSON() : _schema);
+
+    return decorator;
+  };
+
+  return decorator;
+}

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

@@ -0,0 +1,209 @@
+import {generateSpec, getSpec, OperationPath, Path, SpecTypes} from "../../index.js";
+import {InFile} from "./inFile.js";
+
+describe("@File()", () => {
+  describe("one file", () => {
+    @Path("/")
+    class TestController {
+      @OperationPath("POST", "/")
+      test(@InFile("file1") file: any) {}
+    }
+
+    it("should set endpoint metadata - OS2", async () => {
+      expect(await generateSpec({tokens: [{token: TestController}], specType: SpecTypes.SWAGGER})).toEqual({
+        consumes: ["application/json"],
+        info: {
+          title: "Api documentation",
+          version: "1.0.0"
+        },
+        paths: {
+          "/": {
+            post: {
+              consumes: ["multipart/form-data"],
+              operationId: "testControllerTest",
+              parameters: [
+                {
+                  format: "binary",
+                  in: "formData",
+                  name: "file1",
+                  type: "string"
+                }
+              ],
+              produces: ["application/octet-stream"],
+              responses: {
+                "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",
+                  schema: {
+                    type: "object"
+                  }
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        produces: ["application/json"],
+        swagger: "2.0",
+        tags: [
+          {
+            name: "TestController"
+          }
+        ]
+      });
+    });
+
+    it("should set endpoint metadata - OS3", () => {
+      expect(getSpec(TestController, {specType: SpecTypes.OPENAPI})).toEqual({
+        paths: {
+          "/": {
+            post: {
+              operationId: "testControllerTest",
+              parameters: [],
+              requestBody: {
+                content: {
+                  "multipart/form-data": {
+                    schema: {
+                      properties: {
+                        file1: {
+                          format: "binary",
+                          type: "string"
+                        }
+                      },
+                      type: "object"
+                    }
+                  }
+                },
+                required: false
+              },
+              responses: {
+                "400": {
+                  content: {
+                    "*/*": {
+                      schema: {
+                        type: "object"
+                      }
+                    }
+                  },
+                  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"
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        tags: [
+          {
+            name: "TestController"
+          }
+        ]
+      });
+    });
+  });
+  describe("many files", () => {
+    @Path("/")
+    class TestController {
+      @OperationPath("POST", "/")
+      test(@InFile("file1") file: any[]) {}
+    }
+
+    it("should set endpoint metadata - OS2", async () => {
+      expect(await generateSpec({tokens: [{token: TestController}], specType: SpecTypes.SWAGGER})).toEqual({
+        consumes: ["application/json"],
+        info: {
+          title: "Api documentation",
+          version: "1.0.0"
+        },
+        paths: {
+          "/": {
+            post: {
+              consumes: ["multipart/form-data"],
+              operationId: "testControllerTest",
+              parameters: [
+                {
+                  collectionFormat: "csv",
+                  in: "formData",
+                  items: {
+                    format: "binary",
+                    type: "string"
+                  },
+                  name: "file1",
+                  type: "array"
+                }
+              ],
+              produces: ["application/octet-stream"],
+              responses: {
+                "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",
+                  schema: {
+                    type: "object"
+                  }
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        produces: ["application/json"],
+        swagger: "2.0",
+        tags: [
+          {
+            name: "TestController"
+          }
+        ]
+      });
+    });
+    it("should set endpoint metadata - OS3", () => {
+      expect(getSpec(TestController, {specType: SpecTypes.OPENAPI})).toEqual({
+        paths: {
+          "/": {
+            post: {
+              operationId: "testControllerTest",
+              parameters: [],
+              requestBody: {
+                content: {
+                  "multipart/form-data": {
+                    schema: {
+                      properties: {
+                        file1: {
+                          items: {
+                            format: "binary",
+                            type: "string"
+                          },
+                          type: "array"
+                        }
+                      },
+                      type: "object"
+                    }
+                  }
+                },
+                required: false
+              },
+              responses: {
+                "400": {
+                  content: {
+                    "*/*": {
+                      schema: {
+                        type: "object"
+                      }
+                    }
+                  },
+                  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"
+                }
+              },
+              tags: ["TestController"]
+            }
+          }
+        },
+        tags: [
+          {
+            name: "TestController"
+          }
+        ]
+      });
+    });
+  });
+});