@tsed/schema 8.11.1 → 8.12.0-rc.1

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

@@ -1,582 +0,0 @@
-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

@@ -1,130 +0,0 @@
-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);
-}