@nestia/sdk 3.10.0 → 3.11.0-dev.20240813

package/src/generates/SwaggerGenerator.ts

@@ -2,311 +2,101 @@ import { OpenApi, OpenApiV3, SwaggerV2 } from "@samchon/openapi";
 import fs from "fs";
 import path from "path";
 import { Singleton } from "tstl";
-import ts from "typescript";
 import typia, { IJsonApplication } from "typia";
-import { MetadataCollection } from "typia/lib/factories/MetadataCollection";
 import { JsonApplicationProgrammer } from "typia/lib/programmers/json/JsonApplicationProgrammer";
+import { Metadata } from "typia/lib/schemas/metadata/Metadata";
 
 import { INestiaConfig } from "../INestiaConfig";
-import { INestiaProject } from "../structures/INestiaProject";
-import { ISwaggerError } from "../structures/ISwaggerError";
-import { ISwaggerLazyProperty } from "../structures/ISwaggerLazyProperty";
-import { ISwaggerLazySchema } from "../structures/ISwaggerLazySchema";
+import { ITypedApplication } from "../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
-import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
+import { ITypedHttpRouteParameter } from "../structures/ITypedHttpRouteParameter";
 import { FileRetriever } from "../utils/FileRetriever";
-import { MapUtil } from "../utils/MapUtil";
-import { SwaggerDescriptionGenerator } from "./internal/SwaggerDescriptionGenerator";
-import { SwaggerSchemaGenerator } from "./internal/SwaggerSchemaGenerator";
+import { SwaggerOperationComposer } from "./internal/SwaggerOperationComposer";
 
 export namespace SwaggerGenerator {
-  export interface IProps {
-    config: INestiaConfig.ISwaggerConfig;
-    checker: ts.TypeChecker;
-    collection: MetadataCollection;
-    lazySchemas: Array<ISwaggerLazySchema>;
-    lazyProperties: Array<ISwaggerLazyProperty>;
-    errors: ISwaggerError[];
-    swagger: OpenApi.IDocument;
-  }
-
-  export const generate =
-    (project: INestiaProject) =>
-    async (
-      routeList: Array<ITypedHttpRoute | ITypedWebSocketRoute>,
-    ): Promise<void> => {
-      console.log("Generating Swagger Document");
-
-      // VALIDATE SECURITY
-      const config = project.config.swagger!;
-      const httpRoutes: ITypedHttpRoute[] = routeList.filter(
-        (route): route is ITypedHttpRoute => route.protocol === "http",
-      ) as ITypedHttpRoute[];
-      validate_security(config)(httpRoutes);
-
-      // PREPARE ASSETS
-      const parsed: path.ParsedPath = path.parse(config.output);
-      const directory: string = path.dirname(parsed.dir);
-      if (fs.existsSync(directory) === false)
-        try {
-          await fs.promises.mkdir(directory);
-        } catch {}
-      if (fs.existsSync(directory) === false)
-        throw new Error(
-          `Error on NestiaApplication.swagger(): failed to create output directory: ${directory}`,
-        );
-
-      // COMPOSE SWAGGER DOCUMENT
-      const location: string = !!parsed.ext
-        ? path.resolve(config.output)
-        : path.join(path.resolve(config.output), "swagger.json");
-      const swagger: OpenApi.IDocument = await compose(project)(routeList);
-
-      // DO GENERATE
-      const document:
-        | OpenApi.IDocument
-        | SwaggerV2.IDocument
-        | OpenApiV3.IDocument =
-        config.openapi === "2.0"
-          ? OpenApi.downgrade(swagger, config.openapi as "2.0")
-          : config.openapi === "3.0"
-            ? OpenApi.downgrade(swagger, config.openapi as "3.0")
-            : swagger;
-      await fs.promises.writeFile(
-        location,
-        !config.beautify
-          ? JSON.stringify(document)
-          : JSON.stringify(
-              document,
-              null,
-              typeof config.beautify === "number" ? config.beautify : 2,
-            ),
-        "utf8",
+  export const generate = async (app: ITypedApplication): Promise<void> => {
+    // GET CONFIGURATION
+    if (app.project.config.swagger === undefined)
+      throw new Error("Swagger configuration is not defined.");
+    const config: INestiaConfig.ISwaggerConfig = app.project.config.swagger;
+
+    // TARGET LOCATION
+    const parsed: path.ParsedPath = path.parse(config.output);
+    const directory: string = path.dirname(parsed.dir);
+    if (fs.existsSync(directory) === false)
+      try {
+        await fs.promises.mkdir(directory);
+      } catch {}
+    if (fs.existsSync(directory) === false)
+      throw new Error(
+        `Error on NestiaApplication.swagger(): failed to create output directory: ${directory}`,
       );
-    };
-
-  export const compose =
-    (project: INestiaProject) =>
-    async (
-      routeList: Array<ITypedHttpRoute | ITypedWebSocketRoute>,
-    ): Promise<OpenApi.IDocument> => {
-      // VALIDATE SECURITY
-      const config = project.config.swagger!;
-      const httpRoutes: ITypedHttpRoute[] = routeList.filter(
-        (route): route is ITypedHttpRoute => route.protocol === "http",
-      ) as ITypedHttpRoute[];
-      validate_security(config)(httpRoutes);
-
-      const collection: MetadataCollection = new MetadataCollection({
-        replace: MetadataCollection.replace,
-      });
-
-      // CONSTRUCT SWAGGER DOCUMENTS
-      const errors: ISwaggerError[] = [];
-      const lazySchemas: Array<ISwaggerLazySchema> = [];
-      const lazyProperties: Array<ISwaggerLazyProperty> = [];
-      const swagger: OpenApi.IDocument = await initialize(config);
-      const pathDict: Map<
-        string,
-        Record<string, OpenApi.IOperation>
-      > = new Map();
-
-      for (const route of httpRoutes) {
-        if (route.jsDocTags.find((tag) => tag.name === "internal")) continue;
-
-        const path: Record<string, OpenApi.IOperation> = MapUtil.take(
-          pathDict,
-          get_path(route.path, route.parameters),
-          () => ({}),
-        );
-        path[route.method.toLowerCase()] = generate_route({
-          config,
-          checker: project.checker,
-          collection,
-          lazySchemas,
-          lazyProperties,
-          errors,
-          swagger,
-        })(route);
-      }
-      swagger.paths = {};
-      for (const [path, routes] of pathDict) swagger.paths[path] = routes;
-
-      // FILL JSON-SCHEMAS
-      const application: IJsonApplication<"3.1"> =
-        JsonApplicationProgrammer.write("3.1")(
-          lazySchemas.map(({ metadata }) => metadata),
-        ) as IJsonApplication<"3.1">;
-      swagger.components = {
-        ...(swagger.components ?? {}),
-        ...(application.components ?? {}),
-      };
-      lazySchemas.forEach(({ schema }, index) => {
-        Object.assign(schema, application.schemas[index]!);
-      });
-      for (const p of lazyProperties)
-        Object.assign(
-          p.schema,
-          (
-            application.components.schemas?.[
-              p.object
-            ] as OpenApi.IJsonSchema.IObject
-          )?.properties?.[p.property] ?? {},
-        );
-
-      // CONFIGURE SECURITY
-      if (config.security) fill_security(config.security, swagger);
-
-      // REPORT ERRORS
-      if (errors.length) {
-        for (const e of errors)
-          console.error(
-            `${path.relative(process.cwd(), e.route.location)}:${
-              e.route.controller.name
-            }.${e.route.name}:${
-              e.from
-            } - error TS(@nestia/sdk): invalid type detected.\n\n` +
-              e.messages.map((m) => `  - ${m}`).join("\n"),
-            "\n\n",
-          );
-        throw new TypeError("Invalid type detected");
-      }
-
-      // SWAGGER CUSTOMIZER
-      const customizer = {
-        at: new Singleton(() => {
-          const functor: Map<Function, Endpoint> = new Map();
-          for (const route of httpRoutes) {
-            const method: OpenApi.Method =
-              route.method.toLowerCase() as OpenApi.Method;
-            const path: string = get_path(route.path, route.parameters);
-            const operation: OpenApi.IOperation | undefined =
-              swagger.paths?.[path]?.[method];
-            if (operation === undefined) continue;
-            functor.set(route.function, {
-              method,
-              path,
-              route: operation,
-            });
-          }
-          return functor;
-        }),
-        get: new Singleton(
-          () =>
-            (key: Accessor): OpenApi.IOperation | undefined => {
-              const method: OpenApi.Method =
-                key.method.toLowerCase() as OpenApi.Method;
-              const path: string =
-                "/" +
-                key.path
-                  .split("/")
-                  .filter((str) => !!str.length)
-                  .map((str) =>
-                    str.startsWith(":") ? `{${str.substring(1)}}` : str,
-                  )
-                  .join("/");
-              return swagger.paths?.[path]?.[method];
-            },
-        ),
-      };
-      for (const route of httpRoutes) {
-        if (
-          false ===
-          Reflect.hasMetadata(
-            "nestia/SwaggerCustomizer",
-            route.controller.prototype,
-            route.name,
-          )
-        )
-          continue;
-
-        const path: string = get_path(route.path, route.parameters);
-        const method: OpenApi.Method =
-          route.method.toLowerCase() as OpenApi.Method;
-        const target: OpenApi.IOperation | undefined =
-          swagger.paths?.[path]?.[method];
-        if (target === undefined) continue;
-
-        const closure: Function | Function[] = Reflect.getMetadata(
-          "nestia/SwaggerCustomizer",
-          route.controller.prototype,
-          route.name,
-        );
-        const array: Function[] = Array.isArray(closure) ? closure : [closure];
-        for (const fn of array)
-          fn({
-            route: target,
-            method,
-            path,
-            swagger,
-            at: (func: Function) => customizer.at.get().get(func),
-            get: (accessor: Accessor) => customizer.get.get()(accessor),
-          });
-      }
-      return swagger;
-    };
-
-  const validate_security =
-    (config: INestiaConfig.ISwaggerConfig) =>
-    (routeList: ITypedHttpRoute[]): void | never => {
-      const securityMap: Map<
-        string,
-        { scheme: OpenApi.ISecurityScheme; scopes: Set<string> }
-      > = new Map();
-      for (const [key, value] of Object.entries(config.security ?? {}))
-        securityMap.set(key, {
-          scheme: emend_security(value),
-          scopes:
-            value.type === "oauth2"
-              ? new Set([
-                  ...Object.keys(value.flows.authorizationCode?.scopes ?? {}),
-                  ...Object.keys(value.flows.implicit?.scopes ?? {}),
-                  ...Object.keys(value.flows.password?.scopes ?? {}),
-                  ...Object.keys(value.flows.clientCredentials?.scopes ?? {}),
-                ])
-              : new Set(),
-        });
-
-      const validate =
-        (reporter: (str: string) => void) =>
-        (key: string, scopes: string[]) => {
-          const security = securityMap.get(key);
-          if (security === undefined)
-            return reporter(`target security scheme "${key}" does not exists.`);
-          else if (scopes.length === 0) return;
-          else if (security.scheme.type !== "oauth2")
-            return reporter(
-              `target security scheme "${key}" is not "oauth2" type, but you've configured the scopes.`,
-            );
-          for (const s of scopes)
-            if (security.scopes.has(s) === false)
-              reporter(
-                `target security scheme "${key}" does not have a specific scope "${s}".`,
-              );
-        };
-
-      const violations: string[] = [];
-      for (const route of routeList)
-        for (const record of route.security)
-          for (const [key, scopes] of Object.entries(record))
-            validate((str) =>
-              violations.push(
-                `  - ${str} (${route.controller.name}.${route.name}() at "${route.location}")`,
-              ),
-            )(key, scopes);
+    const location: string = !!parsed.ext
+      ? path.resolve(config.output)
+      : path.join(path.resolve(config.output), "swagger.json");
+
+    // COMPOSE SWAGGER DOCUMENT
+    const document: OpenApi.IDocument = compose({
+      config,
+      routes: app.routes.filter((route) => route.protocol === "http"),
+      document: await initialize(config),
+    });
+    const specified:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument =
+      config.openapi === "2.0"
+        ? OpenApi.downgrade(document, config.openapi as "2.0")
+        : config.openapi === "3.0"
+          ? OpenApi.downgrade(document, config.openapi as "3.0")
+          : document;
+    await fs.promises.writeFile(
+      location,
+      !config.beautify
+        ? JSON.stringify(specified)
+        : JSON.stringify(
+            specified,
+            null,
+            typeof config.beautify === "number" ? config.beautify : 2,
+          ),
+      "utf8",
+    );
+  };
 
-      if (violations.length)
-        throw new Error(
-          `Error on NestiaApplication.swagger(): invalid security specification. Check your "nestia.config.ts" file's "swagger.security" property, or each controller methods.\n` +
-            `\n` +
-            `List of violations:\n` +
-            violations.join("\n"),
-        );
-    };
+  export const compose = (props: {
+    config: INestiaConfig.ISwaggerConfig;
+    routes: ITypedHttpRoute[];
+    document: OpenApi.IDocument;
+  }): OpenApi.IDocument => {
+    // GATHER METADATA
+    const metadatas: Metadata[] = props.routes
+      .filter((r) => r.protocol === "http")
+      .map((r) => [
+        r.success.metadata,
+        ...r.parameters.map((p) => p.metadata),
+        ...Object.values(r.exceptions).map((e) => e.metadata),
+      ])
+      .flat()
+      .filter((m) => m.size() !== 0);
+
+    // COMPOSE JSON SCHEMAS
+    const json: IJsonApplication = JsonApplicationProgrammer.write("3.1")(
+      metadatas,
+    ) as IJsonApplication;
+    const dict: WeakMap<Metadata, OpenApi.IJsonSchema> = new WeakMap();
+    json.schemas.forEach((schema, i) => dict.set(metadatas[i], schema));
+    const schema = (metadata: Metadata): OpenApi.IJsonSchema | undefined =>
+      dict.get(metadata);
+
+    // COMPOSE DOCUMENT
+    const document: OpenApi.IDocument = props.document;
+    document.components.schemas ??= {};
+    Object.assign(document.components.schemas, json.components.schemas);
+    document.paths = writePaths({ ...props, schema });
+
+    return document;
+  };
 
-  /* ---------------------------------------------------------
-        INITIALIZERS
-    --------------------------------------------------------- */
   export const initialize = async (
     config: INestiaConfig.ISwaggerConfig,
   ): Promise<OpenApi.IDocument> => {
@@ -378,134 +168,42 @@ export namespace SwaggerGenerator {
       paths: {},
       components: {
         schemas: {},
+        securitySchemes: config.security,
       },
       tags: config.tags ?? [],
       "x-samchon-emended": true,
     };
   };
 
-  function get_path(
-    path: string,
-    parameters: ITypedHttpRoute.IParameter[],
-  ): string {
-    const filtered: ITypedHttpRoute.IParameter[] = parameters.filter(
-      (param) => param.category === "param" && !!param.field,
+  const writePaths = (props: {
+    config: INestiaConfig.ISwaggerConfig;
+    document: OpenApi.IDocument;
+    schema: (metadata: Metadata) => OpenApi.IJsonSchema | undefined;
+    routes: ITypedHttpRoute[];
+  }): Record<string, OpenApi.IPath> => {
+    const output: Record<string, OpenApi.IPath> = {};
+    for (const r of props.routes) {
+      const path: string = getPath(r);
+      output[path] ??= {};
+      output[path][r.method.toLowerCase() as "get"] =
+        SwaggerOperationComposer.compose({
+          ...props,
+          route: r,
+        });
+    }
+    return output;
+  };
+
+  const getPath = (route: {
+    path: string;
+    parameters: ITypedHttpRouteParameter[];
+  }): string => {
+    let str: string = route.path;
+    const filtered: ITypedHttpRouteParameter.IParam[] = route.parameters.filter(
+      (param) => param.category === "param",
     );
     for (const param of filtered)
-      path = path.replace(`:${param.field}`, `{${param.field}}`);
-    return path;
-  }
-
-  export const generate_route =
-    (props: IProps) =>
-    (route: ITypedHttpRoute): OpenApi.IOperation => {
-      // FIND REQUEST BODY
-      const body = route.parameters.find((param) => param.category === "body");
-
-      // CONSTRUCT SUMMARY & DESCRIPTION
-      const getJsDocTexts = (name: string): string[] =>
-        route.jsDocTags
-          .filter(
-            (tag) =>
-              tag.name === name &&
-              tag.text &&
-              tag.text.find(
-                (elem) => elem.kind === "text" && elem.text.length,
-              ) !== undefined,
-          )
-          .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
-      const { summary, description } = SwaggerDescriptionGenerator.generate({
-        description: route.description,
-        jsDocTags: route.jsDocTags,
-        kind: "summary",
-      });
-      const deprecated = route.jsDocTags.find(
-        (tag) => tag.name === "deprecated",
-      );
-
-      // CONSTRUCT TAGS
-      const tagSet: Set<string> = new Set([
-        ...route.swaggerTags,
-        ...getJsDocTexts("tag").map((tag) => tag.split(" ")[0]),
-      ]);
-      props.swagger.tags ??= [];
-      for (const tag of tagSet)
-        if (props.swagger.tags!.find((elem) => elem.name === tag) === undefined)
-          props.swagger.tags!.push({ name: tag });
-      for (const texts of getJsDocTexts("tag")) {
-        const [name, ...description] = texts.split(" ");
-        if (description.length)
-          props.swagger.tags!.find(
-            (elem) => elem.name === name,
-          )!.description ??= description.join(" ");
-      }
-
-      // FINALIZE
-      return {
-        deprecated: deprecated ? true : undefined,
-        tags: [...tagSet],
-        operationId:
-          route.operationId ??
-          props.config.operationId?.({
-            class: route.controller.name,
-            function: route.name,
-            method: route.method as "GET",
-            path: route.path,
-          }),
-        parameters: route.parameters
-          .filter((param) => param.category !== "body")
-          .map((param) => SwaggerSchemaGenerator.parameter(props)(route)(param))
-          .flat(),
-        requestBody: body
-          ? SwaggerSchemaGenerator.body(props)(route)(body)
-          : undefined,
-        responses: SwaggerSchemaGenerator.response(props)(route),
-        summary,
-        description,
-        security: route.security.length ? route.security : undefined,
-        ...(props.config.additional === true
-          ? {
-              "x-nestia-namespace": [
-                ...route.path
-                  .split("/")
-                  .filter((str) => str.length && str[0] !== ":"),
-                route.name,
-              ].join("."),
-              "x-nestia-jsDocTags": route.jsDocTags,
-              "x-nestia-method": route.method,
-            }
-          : {}),
-      };
-    };
-
-  function fill_security(
-    security: Required<INestiaConfig.ISwaggerConfig>["security"],
-    swagger: OpenApi.IDocument,
-  ): void {
-    swagger.components.securitySchemes = {};
-    for (const [key, value] of Object.entries(security))
-      swagger.components.securitySchemes[key] = emend_security(value);
-  }
-
-  function emend_security(
-    input: OpenApi.ISecurityScheme,
-  ): OpenApi.ISecurityScheme {
-    if (input.type === "apiKey")
-      return {
-        ...input,
-        in: input.in ?? "header",
-        name: input.name ?? "Authorization",
-      };
-    return input;
-  }
-}
-
-interface Accessor {
-  method: string;
-  path: string;
-}
-interface Endpoint {
-  method: string;
-  path: string;
-  route: OpenApi.IOperation;
+      str = str.replace(`:${param.field}`, `{${param.field}}`);
+    return str;
+  };
 }

package/src/generates/internal/E2eFileProgrammer.ts

@@ -7,7 +7,6 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkImportWizard } from "./SdkImportWizard";
-import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
 export namespace E2eFileProgrammer {
   export const generate =
@@ -19,9 +18,9 @@ export namespace E2eFileProgrammer {
       );
       if (project.config.clone !== true)
         for (const tuple of route.imports)
-          for (const instance of tuple[1])
+          for (const instance of tuple.instances)
             importer.internal({
-              file: tuple[0],
+              file: tuple.file,
               type: true,
               instance,
             });
@@ -91,7 +90,7 @@ export namespace E2eFileProgrammer {
                             SdkImportWizard.typia(importer),
                           ),
                         )("random"),
-                        [getTypeName(project)(importer)(headers)],
+                        [SdkAliasCollection.name(headers.type)],
                         undefined,
                       ),
                     ),
@@ -117,7 +116,7 @@ export namespace E2eFileProgrammer {
                 IdentifierFactory.access(
                   ts.factory.createIdentifier(SdkImportWizard.typia(importer)),
                 )("random"),
-                [getTypeName(project)(importer)(p)],
+                [SdkAliasCollection.name(p.type)],
                 undefined,
               ),
             ),
@@ -151,7 +150,7 @@ export namespace E2eFileProgrammer {
                   "output",
                   undefined,
                   project.config.propagate !== true &&
-                    route.output.typeName === "void"
+                    route.success.type.name === "void"
                     ? undefined
                     : SdkAliasCollection.output(project)(importer)(route),
                   ts.factory.createAwaitExpression(caller),
@@ -168,11 +167,3 @@ export namespace E2eFileProgrammer {
 
 const getFunctionName = (route: ITypedHttpRoute): string =>
   ["test", "api", ...route.accessors].join("_");
-
-const getTypeName =
-  (project: INestiaProject) =>
-  (importer: ImportDictionary) =>
-  (p: ITypedHttpRoute.IParameter | ITypedHttpRoute.IOutput) =>
-    p.metadata
-      ? SdkTypeProgrammer.write(project)(importer)(p.metadata)
-      : ts.factory.createTypeReferenceNode(p.typeName);