@nestia/sdk 10.0.2 → 11.0.0-dev.20260312

package/src/generates/internal/SwaggerOperationComposer.ts

@@ -1,119 +1,119 @@
-import { OpenApi } from "@samchon/openapi";
-import { Metadata } from "typia/lib/schemas/metadata/Metadata";
-
-import { INestiaConfig } from "../../INestiaConfig";
-import { SecurityAnalyzer } from "../../analyses/SecurityAnalyzer";
-import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
-import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
-import { SwaggerOperationParameterComposer } from "./SwaggerOperationParameterComposer";
-import { SwaggerOperationResponseComposer } from "./SwaggerOperationResponseComposer";
-
-export namespace SwaggerOperationComposer {
-  export const compose = (props: {
-    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
-    document: OpenApi.IDocument;
-    schema: (metadata: Metadata) => OpenApi.IJsonSchema | undefined;
-    route: ITypedHttpRoute;
-  }): OpenApi.IOperation => {
-    // COMPOSE TAGS
-    const tags: Set<string> = new Set([
-      ...props.route.controller.tags,
-      ...props.route.tags,
-      ...SwaggerDescriptionComposer.getJsDocTexts({
-        jsDocTags: props.route.jsDocTags,
-        name: "tag",
-      }).map((t) => t.split(" ")[0]),
-    ]);
-    if (tags.size) {
-      props.document.tags ??= [];
-      for (const t of tags)
-        if (props.document.tags.find((elem) => elem.name === t) === undefined)
-          props.document.tags.push({ name: t });
-      for (const texts of SwaggerDescriptionComposer.getJsDocTexts({
-        jsDocTags: props.route.jsDocTags,
-        name: "tag",
-      })) {
-        const [name, ...description] = texts.split(" ");
-        if (description.length)
-          props.document.tags.find(
-            (elem) => elem.name === name,
-          )!.description ??= description.join(" ");
-      }
-    }
-
-    // SECURITY
-    const security: Record<string, string[]>[] = SecurityAnalyzer.merge(
-      ...props.route.controller.security,
-      ...props.route.security,
-      ...props.route.jsDocTags
-        .filter((tag) => tag.name === "security")
-        .map((tag) =>
-          tag.text === undefined
-            ? [{}]
-            : tag.text.map((text) => {
-                const line: string[] = text.text
-                  .split(" ")
-                  .filter((s) => s.trim())
-                  .filter((s) => !!s.length);
-                if (line.length === 0) return {};
-                return {
-                  [line[0]]: line.slice(1),
-                };
-              }),
-        )
-        .flat(),
-    );
-
-    // FINALIZE
-    return {
-      ...SwaggerDescriptionComposer.compose({
-        description: props.route.description,
-        jsDocTags: props.route.jsDocTags,
-        kind: "summary",
-      }),
-      deprecated: props.route.jsDocTags.some((tag) => tag.name === "deprecated")
-        ? true
-        : undefined,
-      tags: Array.from(tags),
-      operationId:
-        props.route.operationId ??
-        props.config.operationId?.({
-          class: props.route.controller.class.name,
-          function: props.route.name,
-          method: props.route.method as "GET",
-          path: props.route.path,
-        }),
-      parameters: [
-        ...props.route.pathParameters,
-        ...props.route.queryParameters,
-        ...(props.route.queryObject ? [props.route.queryObject] : []),
-        ...(props.route.headerObject ? [props.route.headerObject] : []),
-      ]
-        .map((p) =>
-          SwaggerOperationParameterComposer.compose({
-            config: props.config,
-            document: props.document,
-            schema: props.schema(p.metadata)!,
-            parameter: p,
-            jsDocTags: props.route.jsDocTags,
-          }),
-        )
-        .flat(),
-      requestBody: props.route.body
-        ? SwaggerOperationParameterComposer.body({
-            schema: props.schema(props.route.body.metadata)!,
-            jsDocTags: props.route.jsDocTags,
-            parameter: props.route.body,
-          })
-        : undefined,
-      responses: SwaggerOperationResponseComposer.compose({
-        schema: props.schema,
-        route: props.route,
-      }),
-      security: security.length ? security : undefined,
-      ...(props.route.extensions ?? {}),
-      "x-samchon-accessor": props.route.accessor,
-      "x-samchon-controller": props.route.controller.class.name,
-    };
-  };
-}
+import { MetadataSchema } from "@typia/core";
+import { OpenApi } from "@typia/interface";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { SecurityAnalyzer } from "../../analyses/SecurityAnalyzer";
+import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
+import { SwaggerOperationParameterComposer } from "./SwaggerOperationParameterComposer";
+import { SwaggerOperationResponseComposer } from "./SwaggerOperationResponseComposer";
+
+export namespace SwaggerOperationComposer {
+  export const compose = (props: {
+    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
+    document: OpenApi.IDocument;
+    schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;
+    route: ITypedHttpRoute;
+  }): OpenApi.IOperation => {
+    // COMPOSE TAGS
+    const tags: Set<string> = new Set([
+      ...props.route.controller.tags,
+      ...props.route.tags,
+      ...SwaggerDescriptionComposer.getJsDocTexts({
+        jsDocTags: props.route.jsDocTags,
+        name: "tag",
+      }).map((t) => t.split(" ")[0]!),
+    ]);
+    if (tags.size) {
+      props.document.tags ??= [];
+      for (const t of tags)
+        if (props.document.tags.find((elem) => elem.name === t) === undefined)
+          props.document.tags.push({ name: t });
+      for (const texts of SwaggerDescriptionComposer.getJsDocTexts({
+        jsDocTags: props.route.jsDocTags,
+        name: "tag",
+      })) {
+        const [name, ...description] = texts.split(" ");
+        if (description.length)
+          props.document.tags.find(
+            (elem) => elem.name === name,
+          )!.description ??= description.join(" ");
+      }
+    }
+
+    // SECURITY
+    const security: Record<string, string[]>[] = SecurityAnalyzer.merge(
+      ...props.route.controller.security,
+      ...props.route.security,
+      ...props.route.jsDocTags
+        .filter((tag) => tag.name === "security")
+        .map((tag) =>
+          tag.text === undefined
+            ? [{}]
+            : tag.text.map((text) => {
+                const line: string[] = text.text
+                  .split(" ")
+                  .filter((s) => s.trim())
+                  .filter((s) => !!s.length);
+                if (line.length === 0) return {};
+                return {
+                  [line[0]!]: line.slice(1),
+                };
+              }),
+        )
+        .flat(),
+    );
+
+    // FINALIZE
+    return {
+      ...SwaggerDescriptionComposer.compose({
+        description: props.route.description,
+        jsDocTags: props.route.jsDocTags,
+        kind: "summary",
+      }),
+      deprecated: props.route.jsDocTags.some((tag) => tag.name === "deprecated")
+        ? true
+        : undefined,
+      tags: Array.from(tags),
+      operationId:
+        props.route.operationId ??
+        props.config.operationId?.({
+          class: props.route.controller.class.name,
+          function: props.route.name,
+          method: props.route.method as "GET",
+          path: props.route.path,
+        }),
+      parameters: [
+        ...props.route.pathParameters,
+        ...props.route.queryParameters,
+        ...(props.route.queryObject ? [props.route.queryObject] : []),
+        ...(props.route.headerObject ? [props.route.headerObject] : []),
+      ]
+        .map((p) =>
+          SwaggerOperationParameterComposer.compose({
+            config: props.config,
+            document: props.document,
+            schema: props.schema(p.metadata)!,
+            parameter: p,
+            jsDocTags: props.route.jsDocTags,
+          }),
+        )
+        .flat(),
+      requestBody: props.route.body
+        ? SwaggerOperationParameterComposer.body({
+            schema: props.schema(props.route.body.metadata)!,
+            jsDocTags: props.route.jsDocTags,
+            parameter: props.route.body,
+          })
+        : undefined,
+      responses: SwaggerOperationResponseComposer.compose({
+        schema: props.schema,
+        route: props.route,
+      }),
+      security: security.length ? security : undefined,
+      ...(props.route.extensions ?? {}),
+      "x-samchon-accessor": props.route.accessor,
+      "x-samchon-controller": props.route.controller.class.name,
+    };
+  };
+}

package/src/generates/internal/SwaggerOperationParameterComposer.ts

@@ -1,162 +1,161 @@
-import { OpenApi } from "@samchon/openapi";
-import { VariadicSingleton } from "tstl";
-import { IJsDocTagInfo, IJsonSchemaCollection } from "typia";
-import { JsonSchemasProgrammer } from "typia/lib/programmers/json/JsonSchemasProgrammer";
-
-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 =
-      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.isRequired(),
-      ...(props.parameter.encrypted ? { "x-nestia-encrypted": true } : {}),
-    };
-  };
-
-  export 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.isRequired(),
-    description: parameterDescription(props),
-    example: props.parameter.example,
-    examples: props.parameter.examples,
-  });
-
-  export const query = (
-    props: IProps<ITypedHttpRouteParameter.IQuery>,
-  ): OpenApi.IOperation.IParameter[] => decomposible(props);
-
-  export 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.isRequired(),
-      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.properties
-      .filter((p) =>
-        p.jsDocTags.every(
-          (tag) => tag.name !== "hidden" && tag.name !== "ignore",
-        ),
-      )
-      .map((p) => {
-        const json: IJsonSchemaCollection = JsonSchemasProgrammer.write({
-          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.isRequired(),
-          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 { JsonSchemasProgrammer } from "@typia/core";
+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 =
+      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.isRequired(),
+      ...(props.parameter.encrypted ? { "x-nestia-encrypted": true } : {}),
+    };
+  };
+
+  export 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.isRequired(),
+    description: parameterDescription(props),
+    example: props.parameter.example,
+    examples: props.parameter.examples,
+  });
+
+  export const query = (
+    props: IProps<ITypedHttpRouteParameter.IQuery>,
+  ): OpenApi.IOperation.IParameter[] => decomposible(props);
+
+  export 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.isRequired(),
+      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.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.isRequired(),
+        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");
+});