@tsed/schema 8.0.1 → 8.0.3

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

@@ -0,0 +1,40 @@
+import {ContentType, getSpec, OperationPath, SpecTypes} from "../../index.js";
+
+describe("ContentType", () => {
+  it("should create middleware", () => {
+    class Test {
+      @OperationPath("GET", "/")
+      @ContentType("application/json")
+      test() {}
+    }
+
+    const spec = getSpec(Test, {specType: SpecTypes.OPENAPI});
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "testTest",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["Test"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Test"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/operations/contentType.ts

@@ -0,0 +1,24 @@
+import {Returns} from "./returns.js";
+
+/**
+ * Sets the Content-Type HTTP header to the MIME type as determined by mime.lookup() for the specified type.
+ * If type contains the “/” character, then it sets the `Content-Type` to type.
+ *
+ * ```typescript
+ *  @ContentType('.html');              // => 'text/html'
+ *  @ContentType('html');               // => 'text/html'
+ *  @ContentType('json');               // => 'application/json'
+ *  @ContentType('application/json');   // => 'application/json'
+ *  @ContentType('png');                // => image/png
+ *  private myMethod() {}
+ * ```
+ *
+ * @param type
+ * @decorator
+ * @operation
+ * @response
+ * @headers
+ */
+export function ContentType(type: string) {
+  return Returns().ContentType(type);
+}

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

@@ -0,0 +1,223 @@
+import {catchError} from "@tsed/core";
+import {QueryParams} from "@tsed/platform-params";
+
+import {Deprecated, getSpec, OperationPath, Returns, SpecTypes} from "../../index.js";
+
+describe("Deprecated", () => {
+  it("should store metadata (swagger)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Deprecated(true)
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            deprecated: true,
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (openspec)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Deprecated()
+      get() {}
+    }
+
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            deprecated: true,
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (class)", () => {
+    @Deprecated()
+    class MyController {
+      @OperationPath("GET", "/")
+      get() {}
+
+      @OperationPath("POST", "/")
+      post() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            deprecated: true,
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          },
+          post: {
+            operationId: "myControllerPost",
+            parameters: [],
+            deprecated: true,
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (param)", () => {
+    class MyController {
+      @OperationPath("GET", "/")
+      get(@QueryParams("param") @Deprecated(true) param: string) {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [
+              {
+                deprecated: true,
+                in: "query",
+                name: "param",
+                required: false,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (prop)", () => {
+    class MyModel {
+      @Deprecated()
+      myProp: string;
+    }
+
+    class MyController {
+      @OperationPath("GET", "/")
+      @Returns(200, MyModel)
+      get(@QueryParams("param") @Deprecated(true) param: string) {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [
+              {
+                deprecated: true,
+                in: "query",
+                name: "param",
+                required: false,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/MyModel"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      components: {
+        schemas: {
+          MyModel: {
+            type: "object",
+            properties: {
+              myProp: {
+                type: "string",
+                deprecated: true
+              }
+            }
+          }
+        }
+      }
+    });
+  });
+  it("should throw an error when the decorator is as static func decorator", () => {
+    const error = catchError(() => {
+      class Model {
+        @Deprecated(true)
+        static myStaticFunc() {}
+      }
+    });
+
+    expect(error?.message).toEqual("Deprecated cannot be used as method.static decorator on Model.myStaticFunc");
+  });
+});

package/src/decorators/operations/deprecated.ts

@@ -0,0 +1,49 @@
+import {decorateMethodsOf, decoratorTypeOf, DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonPropertyStore} from "../../domain/JsonPropertyStore.js";
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add deprecated metadata on the decorated element.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ *
+ * @Deprecated()
+ * class MyCtrl {
+ *   @Deprecated()
+ *   @Get("/")
+ *   method(){
+ *   }
+ * }
+ * ```
+ *
+ * @param deprecated
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export function Deprecated(deprecated: boolean = true) {
+  return JsonEntityFn((store, args) => {
+    switch (decoratorTypeOf(args)) {
+      case DecoratorTypes.METHOD:
+        store.operation!.deprecated(deprecated);
+        break;
+      case DecoratorTypes.CLASS:
+        decorateMethodsOf(args[0], Deprecated(deprecated));
+        break;
+      case DecoratorTypes.PARAM:
+        (store as JsonParameterStore).parameter.set("deprecated", deprecated);
+        break;
+      case DecoratorTypes.PROP:
+        (store as JsonPropertyStore).schema.set("deprecated", deprecated);
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(Deprecated, args);
+    }
+  });
+}

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

@@ -0,0 +1,214 @@
+import {getSpec, OperationPath, SpecTypes} from "../../index.js";
+import {Header} from "./header.js";
+
+describe("Header", () => {
+  describe("when is used as method decorator", () => {
+    describe("with one params has object", () => {
+      it("should set Header", () => {
+        class MyController {
+          @Header({"Content-Type": "application/json"})
+          @OperationPath("GET", "/")
+          test() {}
+        }
+
+        const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+        expect(spec).toEqual({
+          paths: {
+            "/": {
+              get: {
+                operationId: "myControllerTest",
+                parameters: [],
+                responses: {
+                  "200": {
+                    content: {
+                      "*/*": {
+                        schema: {
+                          type: "object"
+                        }
+                      }
+                    },
+                    headers: {
+                      "Content-Type": {
+                        example: "application/json",
+                        schema: {
+                          type: "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                tags: ["MyController"]
+              }
+            }
+          },
+          tags: [
+            {
+              name: "MyController"
+            }
+          ]
+        });
+      });
+    });
+    describe("with one param as string", () => {
+      it("should set Header", () => {
+        class MyController {
+          @Header("x-header")
+          @OperationPath("GET", "/")
+          test() {}
+        }
+
+        const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+        expect(spec).toEqual({
+          paths: {
+            "/": {
+              get: {
+                operationId: "myControllerTest",
+                parameters: [],
+                responses: {
+                  "200": {
+                    content: {
+                      "*/*": {
+                        schema: {
+                          type: "object"
+                        }
+                      }
+                    },
+                    headers: {
+                      "x-header": {
+                        schema: {
+                          type: "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                tags: ["MyController"]
+              }
+            }
+          },
+          tags: [
+            {
+              name: "MyController"
+            }
+          ]
+        });
+      });
+    });
+    describe("with two params has object", () => {
+      it("should set Header", () => {
+        class MyController {
+          @OperationPath("GET", "/")
+          @Header("Content-Type", "application/json")
+          test() {}
+        }
+
+        const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+        expect(spec).toEqual({
+          paths: {
+            "/": {
+              get: {
+                operationId: "myControllerTest",
+                parameters: [],
+                responses: {
+                  "200": {
+                    content: {
+                      "*/*": {
+                        schema: {
+                          type: "object"
+                        }
+                      }
+                    },
+                    headers: {
+                      "Content-Type": {
+                        example: "application/json",
+                        schema: {
+                          type: "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                tags: ["MyController"]
+              }
+            }
+          },
+          tags: [
+            {
+              name: "MyController"
+            }
+          ]
+        });
+      });
+    });
+    describe("with swagger params has object", () => {
+      it("should set Header", () => {
+        class MyController {
+          @OperationPath("GET", "/")
+          @Header({
+            "Content-Type": "text/plain",
+            "Content-Length": 123,
+            ETag: {
+              value: "12345",
+              description: "header description"
+            }
+          } as any)
+          test() {}
+        }
+
+        const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+        expect(spec).toEqual({
+          paths: {
+            "/": {
+              get: {
+                operationId: "myControllerTest",
+                parameters: [],
+                responses: {
+                  "200": {
+                    content: {
+                      "*/*": {
+                        schema: {
+                          type: "object"
+                        }
+                      }
+                    },
+                    headers: {
+                      "Content-Length": {
+                        example: 123,
+                        schema: {
+                          type: "number"
+                        }
+                      },
+                      "Content-Type": {
+                        example: "text/plain",
+                        schema: {
+                          type: "string"
+                        }
+                      },
+                      ETag: {
+                        description: "header description",
+                        example: "12345",
+                        schema: {
+                          type: "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                tags: ["MyController"]
+              }
+            }
+          },
+          tags: [
+            {
+              name: "MyController"
+            }
+          ]
+        });
+      });
+    });
+  });
+});

package/src/decorators/operations/header.ts

@@ -0,0 +1,62 @@
+import {isString} from "@tsed/core";
+
+import {JsonHeader, JsonHeaders} from "../../interfaces/JsonOpenSpec.js";
+import {Returns} from "./returns.js";
+
+/**
+ * Sets the response’s HTTP header field to value. To set multiple fields at once, pass an object as the parameter.
+ *
+ * ```typescript
+ * @Header('Content-Type', 'text/plain');
+ * private myMethod() {}
+ *
+ * @Status(204)
+ * @Header({
+ *   "Content-Type": "text/plain",
+ *   "Content-Length": 123,
+ *   "ETag": {
+ *     "value": "12345",
+ *     "description": "header description"
+ *   }
+ * })
+ * private myMethod() {}
+ * ```
+ *
+ * This example will produce the swagger responses object:
+ *
+ * ```json
+ * {
+ *   "responses": {
+ *     "204": {
+ *       "description": "Description",
+ *       "headers": {
+ *          "Content-Type": {
+ *             "type": "string"
+ *          },
+ *          "Content-Length": {
+ *             "type": "number"
+ *          },
+ *          "ETag": {
+ *             "type": "string",
+ *             "description": "header description"
+ *          }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @operation
+ * @response
+ */
+export function Header(headers: string | number | JsonHeaders, value?: string | number | JsonHeader): Function {
+  if (value !== undefined) {
+    headers = {[headers as string]: value};
+  }
+  if (value === undefined && isString(headers)) {
+    headers = {[headers as string]: {type: "string"}};
+  }
+
+  return Returns().Headers(headers as JsonHeaders);
+}