@nestia/sdk 12.0.0-dev.20260601.1 → 12.0.0-dev.20260612.2

package/src/generates/internal/SwaggerOperationParameterComposer.ts

@@ -1,162 +1,175 @@
-import { JsonSchemasProgrammer, MetadataObjectType } from "../../internal/legacy";
-import { OpenApi } from "@typia/interface";
-import { VariadicSingleton } from "tstl";
-import { IJsDocTagInfo, IJsonSchemaCollection } from "typia";
-
-import { INestiaConfig } from "../../INestiaConfig";
-import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
-import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
-
-export namespace SwaggerOperationParameterComposer {
-  export interface IProps<Parameter extends ITypedHttpRouteParameter> {
-    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
-    document: OpenApi.IDocument;
-    schema: OpenApi.IJsonSchema;
-    jsDocTags: IJsDocTagInfo[];
-    parameter: Parameter;
-  }
-
-  export const compose = (
-    props: IProps<ITypedHttpRouteParameter>,
-  ): OpenApi.IOperation.IParameter[] =>
-    props.parameter.category === "body"
-      ? []
-      : props.parameter.category === "param"
-        ? [path({ ...props, parameter: props.parameter })]
-        : props.parameter.category === "query"
-          ? query({ ...props, parameter: props.parameter })
-          : header({ ...props, parameter: props.parameter });
-
-  export const body = (
-    props: Omit<IProps<ITypedHttpRouteParameter.IBody>, "config" | "document">,
-  ): OpenApi.IOperation.IRequestBody => {
-    const description: string | undefined =
-      props.parameter.description ??
-      SwaggerDescriptionComposer.descriptionFromJsDocTag({
-        jsDocTags: props.jsDocTags,
-        tag: "param",
-        parameter: props.parameter.name,
-      });
-    return {
-      description: props.parameter.encrypted
-        ? `${warning.get(!!description)}${description ?? ""}`
-        : description,
-      content: {
-        [props.parameter.contentType]: {
-          schema: props.schema,
-          example: props.parameter.example,
-          examples: props.parameter.examples,
-        },
-      },
-      required: props.parameter.metadata.required,
-      ...(props.parameter.encrypted ? { "x-nestia-encrypted": true } : {}),
-    };
-  };
-
-  const path = (
-    props: Omit<IProps<ITypedHttpRouteParameter.IPath>, "config" | "document">,
-  ): OpenApi.IOperation.IParameter => ({
-    name: props.parameter.field,
-    in: "path",
-    schema: props.schema,
-    required: props.parameter.metadata.required,
-    description: parameterDescription(props),
-    example: props.parameter.example,
-    examples: props.parameter.examples,
-  });
-
-  const query = (
-    props: IProps<ITypedHttpRouteParameter.IQuery>,
-  ): OpenApi.IOperation.IParameter[] => decomposible(props);
-
-  const header = (
-    props: IProps<ITypedHttpRouteParameter.IHeaders>,
-  ): OpenApi.IOperation.IParameter[] => decomposible(props);
-
-  const parameterDescription = (
-    props: Pick<IProps<ITypedHttpRouteParameter>, "parameter" | "jsDocTags">,
-  ): string | undefined => {
-    return (
-      props.parameter.description ??
-      props.parameter.jsDocTags.find((tag) => tag.name === "description")
-        ?.text?.[0]?.text ??
-      props.jsDocTags
-        .find(
-          (tag) =>
-            tag.name === "param" &&
-            tag.text?.[0]?.text === props.parameter.name,
-        )
-        ?.text?.map((e) => e.text)
-        .join("")
-        .substring(props.parameter.name.length)
-        .trim()
-    );
-  };
-
-  const decomposible = (
-    props: IProps<
-      ITypedHttpRouteParameter.IHeaders | ITypedHttpRouteParameter.IQuery
-    >,
-  ): OpenApi.IOperation.IParameter[] => {
-    const param: OpenApi.IOperation.IParameter = {
-      name: props.parameter.field ?? props.parameter.name,
-      in: props.parameter.category === "query" ? "query" : "header",
-      schema: props.schema,
-      description: parameterDescription(props),
-      required: props.parameter.metadata.required,
-      example: props.parameter.example,
-      examples: props.parameter.examples,
-    };
-    if (
-      props.config.decompose === false ||
-      props.parameter.metadata.objects.length === 0
-    )
-      return [param];
-    return (props.parameter.metadata.objects[0]!.type as MetadataObjectType).properties.filter((p) =>
-      p.jsDocTags.every(
-        (tag) => tag.name !== "hidden" && tag.name !== "ignore",
-      ),
-    ).map((p) => {
-      const json: IJsonSchemaCollection = JsonSchemasProgrammer.writeSchemas({
-        version: "3.1",
-        metadatas: [p.value],
-      }) as IJsonSchemaCollection;
-      if (Object.keys(json.components.schemas ?? {}).length !== 0) {
-        props.document.components ??= {};
-        props.document.components.schemas ??= {};
-        Object.assign(
-          props.document.components.schemas,
-          json.components.schemas,
-        );
-      }
-      return {
-        name: p.key.constants[0]!.values[0]!.value as string,
-        in: props.parameter.category === "query" ? "query" : "header",
-        schema: json.schemas[0]!,
-        required: p.value.required,
-        description: SwaggerDescriptionComposer.compose({
-          description: p.description ?? null,
-          jsDocTags: p.jsDocTags,
-          kind: "title",
-        }).description,
-      };
-    });
-  };
-}
-
-const warning = new VariadicSingleton((described: boolean): string => {
-  const summary = "Request body must be encrypted.";
-  const component =
-    "[EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody)";
-  const content: string[] = [
-    "## Warning",
-    "",
-    summary,
-    "",
-    `The request body data would be encrypted as "AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding", through the ${component} component.`,
-    "",
-    `Therefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.`,
-  ];
-  if (described === true) content.push("", "----------------", "", "");
-  return content.join("\n");
-});
+import { OpenApi } from "@typia/interface";
+import { VariadicSingleton } from "tstl";
+import { IJsDocTagInfo, IJsonSchemaCollection } from "typia";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import {
+  JsonSchemasProgrammer,
+  MetadataObjectType,
+} from "../../internal/legacy";
+import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
+import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
+import { SwaggerReadonlyArrayEmender } from "./SwaggerReadonlyArrayEmender";
+
+export namespace SwaggerOperationParameterComposer {
+  export interface IProps<Parameter extends ITypedHttpRouteParameter> {
+    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
+    document: OpenApi.IDocument;
+    schema: OpenApi.IJsonSchema;
+    jsDocTags: IJsDocTagInfo[];
+    parameter: Parameter;
+  }
+
+  export const compose = (
+    props: IProps<ITypedHttpRouteParameter>,
+  ): OpenApi.IOperation.IParameter[] =>
+    props.parameter.category === "body"
+      ? []
+      : props.parameter.category === "param"
+        ? [path({ ...props, parameter: props.parameter })]
+        : props.parameter.category === "query"
+          ? query({ ...props, parameter: props.parameter })
+          : header({ ...props, parameter: props.parameter });
+
+  export const body = (
+    props: Omit<IProps<ITypedHttpRouteParameter.IBody>, "config" | "document">,
+  ): OpenApi.IOperation.IRequestBody => {
+    const description: string | undefined =
+      props.parameter.description ??
+      SwaggerDescriptionComposer.descriptionFromJsDocTag({
+        jsDocTags: props.jsDocTags,
+        tag: "param",
+        parameter: props.parameter.name,
+      });
+    return {
+      description: props.parameter.encrypted
+        ? `${warning.get(!!description)}${description ?? ""}`
+        : description,
+      content: {
+        [props.parameter.contentType]: {
+          schema: props.schema,
+          example: props.parameter.example,
+          examples: props.parameter.examples,
+        },
+      },
+      required: props.parameter.metadata.required,
+      ...(props.parameter.encrypted ? { "x-nestia-encrypted": true } : {}),
+    };
+  };
+
+  const path = (
+    props: Omit<IProps<ITypedHttpRouteParameter.IPath>, "config" | "document">,
+  ): OpenApi.IOperation.IParameter => ({
+    name: props.parameter.field,
+    in: "path",
+    schema: props.schema,
+    required: props.parameter.metadata.required,
+    description: parameterDescription(props),
+    example: props.parameter.example,
+    examples: props.parameter.examples,
+  });
+
+  const query = (
+    props: IProps<ITypedHttpRouteParameter.IQuery>,
+  ): OpenApi.IOperation.IParameter[] => decomposible(props);
+
+  const header = (
+    props: IProps<ITypedHttpRouteParameter.IHeaders>,
+  ): OpenApi.IOperation.IParameter[] => decomposible(props);
+
+  const parameterDescription = (
+    props: Pick<IProps<ITypedHttpRouteParameter>, "parameter" | "jsDocTags">,
+  ): string | undefined => {
+    return (
+      props.parameter.description ??
+      props.parameter.jsDocTags.find((tag) => tag.name === "description")
+        ?.text?.[0]?.text ??
+      props.jsDocTags
+        .find(
+          (tag) =>
+            tag.name === "param" &&
+            tag.text?.[0]?.text === props.parameter.name,
+        )
+        ?.text?.map((e) => e.text)
+        .join("")
+        .substring(props.parameter.name.length)
+        .trim()
+    );
+  };
+
+  const decomposible = (
+    props: IProps<
+      ITypedHttpRouteParameter.IHeaders | ITypedHttpRouteParameter.IQuery
+    >,
+  ): OpenApi.IOperation.IParameter[] => {
+    const param: OpenApi.IOperation.IParameter = {
+      name: props.parameter.field ?? props.parameter.name,
+      in: props.parameter.category === "query" ? "query" : "header",
+      schema: props.schema,
+      description: parameterDescription(props),
+      required: props.parameter.metadata.required,
+      example: props.parameter.example,
+      examples: props.parameter.examples,
+    };
+    if (
+      props.config.decompose === false ||
+      props.parameter.metadata.objects.length === 0
+    )
+      return [param];
+    return (
+      props.parameter.metadata.objects[0]!.type as MetadataObjectType
+    ).properties
+      .filter((p) =>
+        p.jsDocTags.every(
+          (tag) => tag.name !== "hidden" && tag.name !== "ignore",
+        ),
+      )
+      .map((p) => {
+        const json: IJsonSchemaCollection = JsonSchemasProgrammer.writeSchemas({
+          version: "3.1",
+          metadatas: [p.value],
+        }) as IJsonSchemaCollection;
+        SwaggerReadonlyArrayEmender.emend({
+          components: json.components,
+          schema: json.schemas[0],
+          metadata: p.value,
+        });
+        if (Object.keys(json.components.schemas ?? {}).length !== 0) {
+          props.document.components ??= {};
+          props.document.components.schemas ??= {};
+          Object.assign(
+            props.document.components.schemas,
+            json.components.schemas,
+          );
+        }
+        return {
+          name: p.key.constants[0]!.values[0]!.value as string,
+          in: props.parameter.category === "query" ? "query" : "header",
+          schema: json.schemas[0]!,
+          required: p.value.required,
+          description: SwaggerDescriptionComposer.compose({
+            description: p.description ?? null,
+            jsDocTags: p.jsDocTags,
+            kind: "title",
+          }).description,
+        };
+      });
+  };
+}
+
+const warning = new VariadicSingleton((described: boolean): string => {
+  const summary = "Request body must be encrypted.";
+  const component =
+    "[EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody)";
+  const content: string[] = [
+    "## Warning",
+    "",
+    summary,
+    "",
+    `The request body data would be encrypted as "AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding", through the ${component} component.`,
+    "",
+    `Therefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.`,
+  ];
+  if (described === true) content.push("", "----------------", "", "");
+  return content.join("\n");
+});

package/src/generates/internal/SwaggerOperationResponseComposer.ts

@@ -1,110 +1,115 @@
-import { MetadataSchema } from "../../internal/legacy";
-import { OpenApi } from "@typia/interface";
-import { VariadicSingleton } from "tstl";
-
-import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
-import { StringUtil } from "../../utils/StringUtil";
-import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
-
-export namespace SwaggerOperationResponseComposer {
-  export const compose = (props: {
-    schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;
-    route: ITypedHttpRoute;
-  }): Record<string, OpenApi.IOperation.IResponse> => {
-    const output: Record<string, OpenApi.IOperation.IResponse> = {};
-    // FROM DECORATOR
-    for (const [status, error] of Object.entries(props.route.exceptions))
-      output[status] = {
-        description: error.description ?? undefined,
-        content: {
-          "application/json": {
-            schema: props.schema(error.metadata),
-            example: error.example,
-            examples: error.examples,
-          },
-        },
-      };
-
-    // FROM COMMENTS
-    for (const tag of props.route.jsDocTags) {
-      if (tag.name !== "throw" && tag.name !== "throws") continue;
-      const text: string | undefined = tag.text?.find(
-        (elem) => elem.kind === "text",
-      )?.text;
-      if (text === undefined) continue;
-
-      const elements: string[] = text.split(" ").map((str) => str.trim());
-      const status: string = elements[0]!;
-      if (
-        isNaN(Number(status)) &&
-        status !== "2XX" &&
-        status !== "3XX" &&
-        status !== "4XX" &&
-        status !== "5XX"
-      )
-        continue;
-
-      const description: string | undefined =
-        elements.length === 1 ? undefined : elements.slice(1).join(" ");
-      const oldbie = output[status];
-      if (description && oldbie !== undefined)
-        oldbie.description ??= description;
-      else if (oldbie === undefined)
-        output[status] = {
-          description: description,
-          content: {
-            "application/json": {
-              schema: {},
-            },
-          },
-        };
-    }
-
-    // SUCCESS
-    const description: string | undefined =
-      SwaggerDescriptionComposer.descriptionFromJsDocTag({
-        jsDocTags: props.route.jsDocTags,
-        tag: "returns",
-      }) ??
-      SwaggerDescriptionComposer.descriptionFromJsDocTag({
-        jsDocTags: props.route.jsDocTags,
-        tag: "return",
-      });
-    output[
-      props.route.success.status ??
-        (props.route.method.toLowerCase() === "post" ? 201 : 200)
-    ] = {
-      description: props.route.success.encrypted
-        ? `${warning.get(!!description, props.route.method)}${description ?? ""}`
-        : (description ?? ""),
-      content: props.route.success.contentType
-        ? {
-            [props.route.success.contentType]: {
-              schema: props.schema(props.route.success.metadata),
-              example: props.route.success.example,
-              examples: props.route.success.examples,
-            },
-          }
-        : undefined,
-      ...(props.route.success.encrypted ? { "x-nestia-encrypted": true } : {}),
-    };
-    return output;
-  };
-}
-
-const warning = new VariadicSingleton((described: boolean, method: string) => {
-  const summary: string = "Response data have been encrypted.";
-  const component: string = `[EncryptedRoute.${StringUtil.capitalize(method)}](https://github.com/samchon/@nestia/core#encryptedroute)`;
-
-  const content: string[] = [
-    "## Warning",
-    "",
-    summary,
-    "",
-    `The response body data would be encrypted as "AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding", through the ${component} component.`,
-    "",
-    `Therefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.`,
-  ];
-  if (described === true) content.push("", "----------------", "", "");
-  return content.join("\n");
-});
+import { OpenApi } from "@typia/interface";
+import { VariadicSingleton } from "tstl";
+
+import { MetadataSchema } from "../../internal/legacy";
+import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { StringUtil } from "../../utils/StringUtil";
+import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
+
+export namespace SwaggerOperationResponseComposer {
+  export const compose = (props: {
+    schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;
+    route: ITypedHttpRoute;
+  }): Record<string, OpenApi.IOperation.IResponse> => {
+    const output: Record<string, OpenApi.IOperation.IResponse> = {};
+    // FROM DECORATOR
+    for (const [status, error] of Object.entries(props.route.exceptions))
+      output[status] = {
+        description: error.description ?? undefined,
+        content: {
+          "application/json": {
+            schema: props.schema(error.metadata),
+            example: error.example,
+            examples: error.examples,
+          },
+        },
+      };
+
+    // FROM COMMENTS
+    for (const tag of props.route.jsDocTags) {
+      if (tag.name !== "throw" && tag.name !== "throws") continue;
+      const text: string | undefined = tag.text?.find(
+        (elem) => elem.kind === "text",
+      )?.text;
+      if (text === undefined) continue;
+
+      const elements: string[] = text.split(" ").map((str) => str.trim());
+      const status: string = elements[0]!;
+      if (
+        isNaN(Number(status)) &&
+        status !== "2XX" &&
+        status !== "3XX" &&
+        status !== "4XX" &&
+        status !== "5XX"
+      )
+        continue;
+
+      const description: string | undefined =
+        elements.length === 1 ? undefined : elements.slice(1).join(" ");
+      const oldbie = output[status];
+      if (description && oldbie !== undefined)
+        oldbie.description ??= description;
+      else if (oldbie === undefined)
+        output[status] = {
+          description: description,
+          content: {
+            "application/json": {
+              schema: {},
+            },
+          },
+        };
+    }
+
+    // SUCCESS
+    const description: string | undefined =
+      SwaggerDescriptionComposer.descriptionFromJsDocTag({
+        jsDocTags: props.route.jsDocTags,
+        tag: "returns",
+      }) ??
+      SwaggerDescriptionComposer.descriptionFromJsDocTag({
+        jsDocTags: props.route.jsDocTags,
+        tag: "return",
+      });
+    output[
+      props.route.success.status ??
+        (props.route.method.toLowerCase() === "post" ? 201 : 200)
+    ] = {
+      description: props.route.success.encrypted
+        ? `${warning.get(!!description, props.route.method)}${description ?? ""}`
+        : (description ?? ""),
+      content: props.route.success.contentType
+        ? {
+            [props.route.success.contentType]: {
+              schema: props.route.success.binary
+                ? {
+                    format: "binary",
+                    type: "string",
+                  }
+                : props.schema(props.route.success.metadata),
+              example: props.route.success.example,
+              examples: props.route.success.examples,
+            },
+          }
+        : undefined,
+      ...(props.route.success.encrypted ? { "x-nestia-encrypted": true } : {}),
+    };
+    return output;
+  };
+}
+
+const warning = new VariadicSingleton((described: boolean, method: string) => {
+  const summary: string = "Response data have been encrypted.";
+  const component: string = `[EncryptedRoute.${StringUtil.capitalize(method)}](https://github.com/samchon/@nestia/core#encryptedroute)`;
+
+  const content: string[] = [
+    "## Warning",
+    "",
+    summary,
+    "",
+    `The response body data would be encrypted as "AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding", through the ${component} component.`,
+    "",
+    `Therefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.`,
+  ];
+  if (described === true) content.push("", "----------------", "", "");
+  return content.join("\n");
+});