@tsed/schema 8.0.0 → 8.0.2

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

@@ -0,0 +1,582 @@
+import "@tsed/platform-exceptions";
+
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {getSpec} from "../../utils/getSpec.js";
+import {CollectionOf} from "../collections/collectionOf.js";
+import {Property} from "../common/property.js";
+import {Generics} from "../generics/generics.js";
+import {OperationPath} from "./operationPath.js";
+import {Status} from "./status.js";
+
+describe("@Status", () => {
+  it("should declare a return type", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, String).Description("description"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare a return type (Status().Type())", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200).Type(String).Description("description"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare a return type with headers", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, String)
+        .Description("description")
+        .Header("x-token", "token")
+        .Header("x-header", {
+          value: ""
+        })
+        .Examples({test: "Examples"})
+        .Schema({
+          minLength: 3
+        }))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "*/*": {
+                    examples: {
+                      test: "Examples"
+                    },
+                    schema: {
+                      minLength: 3,
+                      type: "string"
+                    }
+                  }
+                },
+                description: "description",
+                headers: {
+                  "x-header": {
+                    example: "",
+                    schema: {
+                      type: "string"
+                    }
+                  },
+                  "x-token": {
+                    example: "token",
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare a return type with content-type", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, String).Description("description").ContentType("text/html").Examples("Examples"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      tags: [
+        {
+          name: "Controller"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "text/html": {
+                    schema: {
+                      type: "string"
+                    },
+                    examples: ["Examples"]
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      }
+    });
+  });
+  it("should declare error response", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(400).Description("Bad request"))
+      @Status(401)
+      @(Status(200).Description("Success"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          BadRequest: {
+            properties: {
+              errors: {
+                description: "A list of related errors",
+                items: {
+                  $ref: "#/components/schemas/GenericError"
+                },
+                type: "array"
+              },
+              message: {
+                description: "An error message",
+                minLength: 1,
+                type: "string"
+              },
+              name: {
+                default: "BAD_REQUEST",
+                description: "The error name",
+                example: "BAD_REQUEST",
+                minLength: 1,
+                type: "string"
+              },
+              stack: {
+                description: "The stack trace (only in development mode)",
+                type: "string"
+              },
+              status: {
+                default: 400,
+                description: "The status code of the exception",
+                example: 400,
+                type: "number"
+              }
+            },
+            required: ["name", "message", "status"],
+            type: "object"
+          },
+          GenericError: {
+            additionalProperties: true,
+            properties: {
+              message: {
+                description: "An error message",
+                minLength: 1,
+                type: "string"
+              },
+              name: {
+                description: "The error name",
+                minLength: 1,
+                type: "string"
+              }
+            },
+            required: ["name", "message"],
+            type: "object"
+          },
+          Unauthorized: {
+            properties: {
+              errors: {
+                description: "A list of related errors",
+                items: {
+                  $ref: "#/components/schemas/GenericError"
+                },
+                type: "array"
+              },
+              message: {
+                description: "An error message",
+                minLength: 1,
+                type: "string"
+              },
+              name: {
+                default: "UNAUTHORIZED",
+                description: "The error name",
+                example: "UNAUTHORIZED",
+                minLength: 1,
+                type: "string"
+              },
+              stack: {
+                description: "The stack trace (only in development mode)",
+                type: "string"
+              },
+              status: {
+                default: 401,
+                description: "The status code of the exception",
+                example: 401,
+                type: "number"
+              }
+            },
+            required: ["name", "message", "status"],
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                },
+                description: "Success"
+              },
+              "400": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/BadRequest"
+                    }
+                  }
+                },
+                description: "Bad request"
+              },
+              "401": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/Unauthorized"
+                    }
+                  }
+                },
+                description: "Unauthorized"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should throw an error when using of with String", () => {
+    // WHEN
+    let actualError: any;
+    try {
+      class Controller {
+        @OperationPath("POST", "/")
+        @(Status(200, String).Of(Array).Description("description"))
+        method() {}
+      }
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toBe("Returns.Of cannot be used with the following primitive classes: String, Number, Boolean");
+  });
+  it("should throw an error when using of with Collection", () => {
+    // WHEN
+    let actualError: any;
+    try {
+      class Controller {
+        @OperationPath("POST", "/")
+        @(Status(200, Array).Nested(Set).Description("description"))
+        method() {}
+      }
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toBe("Returns.Nested cannot be used with the following classes: Map, Set, Array, String, Number, Boolean");
+  });
+  it("should declare an Array of string", () => {
+    // WHEN
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, Array).Of(String).Description("description"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      items: {
+                        type: "string"
+                      },
+                      type: "array"
+                    }
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare an Array of Model", () => {
+    // WHEN
+    class Model {
+      @Property()
+      id: string;
+    }
+
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, Array).Of(Model).Description("description"))
+      method() {}
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      items: {
+                        $ref: "#/components/schemas/Model"
+                      },
+                      type: "array"
+                    }
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+  it("should declare an Generic of Model", () => {
+    // WHEN
+    @Generics("T")
+    class Pagination<T> {
+      @CollectionOf("T")
+      data: T[];
+
+      @Property()
+      totalCount: number;
+    }
+
+    @Generics("T")
+    class Submission<T> {
+      @Property()
+      _id: string;
+
+      @Property("T")
+      data: T;
+    }
+
+    class Product {
+      @Property()
+      title: string;
+    }
+
+    class Controller {
+      @OperationPath("POST", "/")
+      @(Status(200, Pagination).Of(Submission).Nested(Product).Description("description"))
+      method(): Promise<Pagination<Submission<Product>> | null> {
+        return null as never;
+      }
+    }
+
+    // THEN
+    const spec = getSpec(Controller);
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Product: {
+            properties: {
+              title: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "controllerMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      properties: {
+                        data: {
+                          items: {
+                            properties: {
+                              _id: {
+                                type: "string"
+                              },
+                              data: {
+                                $ref: "#/components/schemas/Product"
+                              }
+                            },
+                            type: "object"
+                          },
+                          type: "array"
+                        },
+                        totalCount: {
+                          type: "number"
+                        }
+                      },
+                      type: "object"
+                    }
+                  }
+                },
+                description: "description"
+              }
+            },
+            tags: ["Controller"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Controller"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/operations/status.ts

@@ -0,0 +1,130 @@
+import {Type} from "@tsed/core";
+
+import {Returns, ReturnsChainedDecorators} from "./returns.js";
+
+/**
+ * Add responses documentation for a specific status code.
+ *
+ * ## Usage
+ *
+ * Ts.ED v6 API introducing the chaining decorator concept.
+ * Now a decorator like Returns can be used with another decorators like Description.
+ *
+ * ```typescript
+ * import {Returns} from "@tsed/schema";
+ *
+ * @Controller("/")
+ * class MyController {
+ *   @Status(404, String).Description("Not Found")
+ *   @Status(200, Model).Description("Success")
+ *   async myMethod(): Promise<Model> {}
+ * }
+ * ```
+ *
+ * ::: tip
+ * TypeScript and your IDE will discover automatically the chained decorators. But for more details you can look on @@ReturnsChainedDecorators@@ interface, to know
+ * what chained decorators are available under Returns decorator.
+ * :::
+ *
+ * This example will produce this documentation in swagger:
+ *
+ * ```json
+ * {
+ *   "responses": {
+ *     "404": {
+ *       "description": "Description",
+ *       "schema": {"type": "string"}
+ *     },
+ *     "2OO": {
+ *       "description": "Description",
+ *       "schema": {"$ref": "..."}
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Declaring a generic model
+ *
+ * Sometime, it might be useful to use generic models. TypeScript doesn't store the generic type in the metadata. This is why we need to
+ * declare explicitly the generic models with the decorators.
+ *
+ * One of the generic's usage, can be a paginated list. With Returns decorator it's now possible to declare generic type and generate the appropriate OpenSpec documentation.
+ *
+ * Starting with the pagination model, by using @@Generics@@ and @@CollectionOf@@:
+ *
+ * ```typescript
+ * @Generics("T")
+ * class Pagination<T> {
+ *  @CollectionOf("T")
+ *  data: T[];
+ *
+ *  @Property()
+ *  totalCount: number;
+ * }
+ * ```
+ *
+ * Now, we need a model to be used with the generic Pagination model:
+ *
+ * ```typescript
+ * class Product {
+ *  @Property()
+ *  id: string;
+ *
+ *  @Property()
+ *  title: string;
+ * }
+ * ```
+ *
+ * Finally, we can use our models on a method as following:
+ *
+ * ```typescript
+ * class Controller {
+ *   @OperationPath("POST", "/")
+ *   @Status(200, Pagination).Of(Product).Description("description")
+ *   async method(): Promise<Pagination<Product> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * ### Declaring a nested generics models <Badge text="6+"/>
+ *
+ * It's also possible to declare a nested generics models in order to have this type `Pagination<Submission<Product>>`:
+ *
+ * ```typescript
+ * import {Post, Generics, Property, Returns} from "@tsed/schema";
+ *
+ * class Controller {
+ *   @Post("/")
+ *   @Status(200, Pagination).Of(Submission).Nested(Product).Description("description")
+ *   async method(): Promise<Pagination<Submission<Product>> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * And here is the Submission model:
+ *
+ * ```typescript
+ * import {Generics, Property} from "@tsed/schema";
+ *
+ * @Generics("T")
+ * class Submission<T> {
+ *   @Property()
+ *   _id: string;
+ *   @Property("T")
+ *   data: T;
+ * }
+ * ```
+ *
+ * @param status
+ * @param model
+ * @decorator
+ * @swagger
+ * @schema
+ * @response
+ * @operation
+ */
+export function Status(status: string | number, model?: Type<any> | any): ReturnsChainedDecorators {
+  return Returns(status, model);
+}