Merge pull request #814 from samchon/features/swagger

Enhance #810 - multiple customization + `at()` method

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@nestia/station",
-  "version": "2.5.10",
+  "version": "2.5.11",
   "description": "Nestia station",
   "main": "prettier.config.js",
   "scripts": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "2.5.10",
+  "version": "2.5.11",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -36,7 +36,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.5.10",
+    "@nestia/fetcher": "^2.5.11",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "detect-ts-node": "^1.0.5",
@@ -48,7 +48,7 @@
     "typia": "^5.4.12"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.5.10",
+    "@nestia/fetcher": ">=2.5.11",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

packages/core/src/decorators/SwaggerCustomizer.ts

@@ -23,12 +23,23 @@ export function SwaggerCustomizer(
     propertyKey: string | symbol,
     descriptor: TypedPropertyDescriptor<any>,
   ) {
-    Reflect.defineMetadata(
-      "nestia/SwaggerCustomizer",
-      closure,
-      target,
-      propertyKey,
-    );
+    const array: Array<(props: SwaggerCustomizer.IProps) => unknown> = (() => {
+      if (Reflect.hasMetadata("nestia/SwaggerCustomizer", target, propertyKey))
+        return Reflect.getMetadata(
+          "nestia/SwaggerCustomizer",
+          target,
+          propertyKey,
+        );
+      const array: Array<(props: SwaggerCustomizer.IProps) => unknown> = [];
+      Reflect.defineMetadata(
+        "nestia/SwaggerCustomizer",
+        array,
+        target,
+        propertyKey,
+      );
+      return array;
+    })();
+    array.push(closure);
     return descriptor;
   };
 }
@@ -61,6 +72,14 @@ export namespace SwaggerCustomizer {
      */
     route: ISwaggerRoute;
 
+    /**
+     * Get neighbor endpoint data through the controller method.
+     *
+     * @param func Controller method to find the neighbor endpoint
+     * @returns Neighbor endpoint data
+     */
+    at(func: Function): ISwaggerEndpoint | undefined;
+
     /**
      * Get neighbor route data.
      *
@@ -84,4 +103,14 @@ export namespace SwaggerCustomizer {
      */
     method: string;
   }
+
+  /**
+   * Endpoint info of the route.
+   */
+  export interface ISwaggerEndpoint extends IAccessor {
+    /**
+     * Route data.
+     */
+    route: ISwaggerRoute;
+  }
 }

packages/fetcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/fetcher",
-  "version": "2.5.10",
+  "version": "2.5.11",
   "description": "Fetcher library of Nestia SDK",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "2.5.10",
+  "version": "2.5.11",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -32,7 +32,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.5.10",
+    "@nestia/fetcher": "^2.5.11",
     "cli": "^1.0.1",
     "get-function-location": "^2.0.0",
     "glob": "^7.2.0",
@@ -45,7 +45,7 @@
     "typia": "^5.4.12"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.5.10",
+    "@nestia/fetcher": ">=2.5.11",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

packages/sdk/src/NestiaSdkApplication.ts

@@ -186,7 +186,7 @@ export class NestiaSdkApplication {
             implicit
               .map(
                 (it) =>
-                  `  - ${it.symbol.class}.${it.symbol.function} at "${it.location}"`,
+                  `  - ${it.target.class.name}.${it.target.function.name} at "${it.location}"`,
               )
               .join("\n"),
         );

packages/sdk/src/analyses/ControllerAnalyzer.ts

@@ -203,9 +203,9 @@ export namespace ControllerAnalyzer {
         },
         imports,
         status: func.status,
-        symbol: {
-          class: controller.name,
-          function: func.name,
+        target: {
+          class: controller.target,
+          function: func.target,
         },
         location: (() => {
           const file = declaration.getSourceFile();

packages/sdk/src/analyses/ReflectAnalyzer.ts

@@ -262,6 +262,7 @@ export namespace ReflectAnalyzer {
 
       // DO CONSTRUCT
       const meta: IController.IFunction = {
+        target: proto,
         name,
         method: method === "ALL" ? "POST" : method,
         paths: _Get_paths(proto).filter((str) => {

packages/sdk/src/generates/SwaggerGenerator.ts

@@ -114,8 +114,8 @@ export namespace SwaggerGenerator {
         for (const e of errors)
           console.error(
             `${path.relative(e.route.location, process.cwd())}:${
-              e.route.symbol.class
-            }.${e.route.symbol.function}:${
+              e.route.target.class.name
+            }.${e.route.target.function.name}:${
               e.from
             } - error TS(@nestia/sdk): invalid type detected.\n\n` +
               e.messages.map((m) => `  - ${m}`).join("\n"),
@@ -125,51 +125,63 @@ export namespace SwaggerGenerator {
       }
 
       // SWAGGER CUSTOMIZER
-      const routeGetter = new Singleton(
-        () =>
-          (accessor: {
-            method: string;
-            path: string;
-          }): ISwaggerRoute | undefined => {
-            const method: string = accessor.method.toLowerCase();
-            const path: string =
-              "/" +
-              accessor.path
-                .split("/")
-                .filter((str) => !!str.length)
-                .map((str) =>
-                  str.startsWith(":") ? `{${str.substring(1)}}` : str,
-                )
-                .join("/");
-            console.log({ path, method });
-            return swagger.paths[path]?.[method];
-          },
-      );
+      const customizer = {
+        at: new Singleton(() => {
+          const functor: Map<Function, Endpoint> = new Map();
+          for (const route of routeList) {
+            const method = route.method.toLowerCase();
+            const path = get_path(route.path, route.parameters);
+            functor.set(route.target.function, {
+              method,
+              path,
+              route: swagger.paths[path][method],
+            });
+          }
+          return functor;
+        }),
+        get: new Singleton(() => (key: Accessor): ISwaggerRoute | undefined => {
+          const method: string = key.method.toLowerCase();
+          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 routeList) {
         if (
           false ===
           Reflect.hasMetadata(
             "nestia/SwaggerCustomizer",
             route.controller.prototype,
-            route.symbol.function,
+            route.target.function.name,
           )
         )
           continue;
+
         const path: string = get_path(route.path, route.parameters);
         const method: string = route.method.toLowerCase();
         const target: ISwaggerRoute = swagger.paths[path][method];
-        const closure: Function = Reflect.getMetadata(
+        const closure: Function | Function[] = Reflect.getMetadata(
           "nestia/SwaggerCustomizer",
           route.controller.prototype,
-          route.symbol.function,
+          route.target.function.name,
         );
-        closure({
-          route: target,
-          method,
-          path,
-          swagger,
-          get: routeGetter.get(),
-        });
+        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),
+          });
       }
 
       // DO GENERATE
@@ -231,7 +243,7 @@ export namespace SwaggerGenerator {
           for (const [key, scopes] of Object.entries(record))
             validate((str) =>
               violations.push(
-                `  - ${str} (${route.symbol} at "${route.location}")`,
+                `  - ${str} (${route.target.class.name}.${route.target.function.name}() at "${route.location}")`,
               ),
             )(key, scopes);
 
@@ -370,8 +382,8 @@ export namespace SwaggerGenerator {
         operationId:
           route.operationId ??
           props.config.operationId?.({
-            class: route.symbol.class,
-            function: route.symbol.function,
+            class: route.target.class.name,
+            function: route.target.function.name,
             method: route.method as "GET",
             path: route.path,
           }),
@@ -422,3 +434,13 @@ export namespace SwaggerGenerator {
     return input;
   }
 }
+
+interface Accessor {
+  method: string;
+  path: string;
+}
+interface Endpoint {
+  method: string;
+  path: string;
+  route: ISwaggerRoute;
+}

packages/sdk/src/generates/internal/SdkRouteProgrammer.ts

@@ -74,7 +74,7 @@ export namespace SdkRouteProgrammer {
     // POSTFIX
     if (!!comments.length) comments.push("");
     comments.push(
-      `@controller ${route.symbol.class}.${route.symbol.function}`,
+      `@controller ${route.target.class.name}.${route.target.function.name}`,
       `@path ${route.method} ${route.path}`,
       `@nestia Generated by Nestia - https://github.com/samchon/nestia`,
     );

packages/sdk/src/structures/IController.ts

@@ -18,6 +18,7 @@ export interface IController {
 
 export namespace IController {
   export interface IFunction {
+    target: Function;
     name: string;
     method: string;
     paths: string[];

packages/sdk/src/structures/IRoute.ts

@@ -17,9 +17,9 @@ export interface IRoute {
   output: IRoute.IOutput;
 
   location: string;
-  symbol: {
-    class: string;
-    function: string;
+  target: {
+    class: Function;
+    function: Function;
   };
   description?: string;
   operationId?: string;

test/features/all/swagger.json

@@ -7,7 +7,7 @@
     }
   ],
   "info": {
-    "version": "2.5.10",
+    "version": "2.5.11-dev.20240224",
     "title": "@nestia/test",
     "description": "Test program of Nestia",
     "license": {

test/features/app-routerModule/src/api/IConnection.ts

@@ -0,0 +1 @@
+export type { IConnection } from "@nestia/fetcher";

test/features/beautify-4/swagger.json

@@ -7,7 +7,7 @@
         }
     ],
     "info": {
-        "version": "2.5.8",
+        "version": "2.5.11-dev.20240224",
         "title": "@nestia/test",
         "description": "Test program of Nestia",
         "license": {

test/features/beautify-false/swagger.json

@@ -1 +1 @@
-{"openapi":"3.0.1","servers":[{"url":"https://github.com/samchon/nestia","description":"insert your server url"}],"info":{"version":"2.5.8","title":"@nestia/test","description":"Test program of Nestia","license":{"name":"MIT"}},"paths":{"/health":{"get":{"tags":["system","health"],"parameters":[],"responses":{"200":{"description":""}},"summary":"Health check API","description":"Health check API.\n\nJust for health checking API liveness."}},"/performance":{"get":{"tags":["system","performance"],"parameters":[],"responses":{"200":{"description":"Performance info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPerformance"}}}}},"summary":"Get server performance info","description":"Get server performance info."}},"/body":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"Content to store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IBbsArticle.IStore"}}},"required":true},"responses":{"201":{"description":"Newly archived article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IBbsArticle"}}}}},"summary":"Store an article","description":"Store an article."}},"/body/{id}":{"put":{"tags":[],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid"},"description":"","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialIBbsArticle.IStore"}}},"required":true},"responses":{"200":{"description":""}}}}},"components":{"schemas":{"IPerformance":{"type":"object","properties":{"cpu":{"$ref":"#/components/schemas/process.global.NodeJS.CpuUsage"},"memory":{"$ref":"#/components/schemas/process.global.NodeJS.MemoryUsage"},"resource":{"$ref":"#/components/schemas/process.global.NodeJS.ResourceUsage"}},"nullable":false,"required":["cpu","memory","resource"],"description":"Performance info."},"process.global.NodeJS.CpuUsage":{"type":"object","properties":{"user":{"type":"number"},"system":{"type":"number"}},"nullable":false,"required":["user","system"]},"process.global.NodeJS.MemoryUsage":{"type":"object","properties":{"rss":{"type":"number"},"heapTotal":{"type":"number"},"heapUsed":{"type":"number"},"external":{"type":"number"},"arrayBuffers":{"type":"number"}},"nullable":false,"required":["rss","heapTotal","heapUsed","external","arrayBuffers"]},"process.global.NodeJS.ResourceUsage":{"type":"object","properties":{"fsRead":{"type":"number"},"fsWrite":{"type":"number"},"involuntaryContextSwitches":{"type":"number"},"ipcReceived":{"type":"number"},"ipcSent":{"type":"number"},"majorPageFault":{"type":"number"},"maxRSS":{"type":"number"},"minorPageFault":{"type":"number"},"sharedMemorySize":{"type":"number"},"signalsCount":{"type":"number"},"swappedOut":{"type":"number"},"systemCPUTime":{"type":"number"},"unsharedDataSize":{"type":"number"},"unsharedStackSize":{"type":"number"},"userCPUTime":{"type":"number"},"voluntaryContextSwitches":{"type":"number"}},"nullable":false,"required":["fsRead","fsWrite","involuntaryContextSwitches","ipcReceived","ipcSent","majorPageFault","maxRSS","minorPageFault","sharedMemorySize","signalsCount","swappedOut","systemCPUTime","unsharedDataSize","unsharedStackSize","userCPUTime","voluntaryContextSwitches"]},"IBbsArticle.IStore":{"type":"object","properties":{"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"required":["title","body","files"]},"IAttachmentFile":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"nullable":true},"extension":{"type":"string","maxLength":8,"minLength":1,"nullable":true},"url":{"type":"string","format":"uri"}},"nullable":false,"required":["name","extension","url"]},"IBbsArticle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"required":["id","created_at","title","body","files"]},"PartialIBbsArticle.IStore":{"type":"object","properties":{"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"description":"Make all properties in T optional"}},"securitySchemes":{"bearer":{"type":"apiKey","in":"header","name":"Authorization"}}}}
+{"openapi":"3.0.1","servers":[{"url":"https://github.com/samchon/nestia","description":"insert your server url"}],"info":{"version":"2.5.11-dev.20240224","title":"@nestia/test","description":"Test program of Nestia","license":{"name":"MIT"}},"paths":{"/health":{"get":{"tags":["system","health"],"parameters":[],"responses":{"200":{"description":""}},"summary":"Health check API","description":"Health check API.\n\nJust for health checking API liveness."}},"/performance":{"get":{"tags":["system","performance"],"parameters":[],"responses":{"200":{"description":"Performance info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPerformance"}}}}},"summary":"Get server performance info","description":"Get server performance info."}},"/body":{"post":{"tags":[],"parameters":[],"requestBody":{"description":"Content to store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IBbsArticle.IStore"}}},"required":true},"responses":{"201":{"description":"Newly archived article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IBbsArticle"}}}}},"summary":"Store an article","description":"Store an article."}},"/body/{id}":{"put":{"tags":[],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid"},"description":"","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialIBbsArticle.IStore"}}},"required":true},"responses":{"200":{"description":""}}}}},"components":{"schemas":{"IPerformance":{"type":"object","properties":{"cpu":{"$ref":"#/components/schemas/process.global.NodeJS.CpuUsage"},"memory":{"$ref":"#/components/schemas/process.global.NodeJS.MemoryUsage"},"resource":{"$ref":"#/components/schemas/process.global.NodeJS.ResourceUsage"}},"nullable":false,"required":["cpu","memory","resource"],"description":"Performance info."},"process.global.NodeJS.CpuUsage":{"type":"object","properties":{"user":{"type":"number"},"system":{"type":"number"}},"nullable":false,"required":["user","system"]},"process.global.NodeJS.MemoryUsage":{"type":"object","properties":{"rss":{"type":"number"},"heapTotal":{"type":"number"},"heapUsed":{"type":"number"},"external":{"type":"number"},"arrayBuffers":{"type":"number"}},"nullable":false,"required":["rss","heapTotal","heapUsed","external","arrayBuffers"]},"process.global.NodeJS.ResourceUsage":{"type":"object","properties":{"fsRead":{"type":"number"},"fsWrite":{"type":"number"},"involuntaryContextSwitches":{"type":"number"},"ipcReceived":{"type":"number"},"ipcSent":{"type":"number"},"majorPageFault":{"type":"number"},"maxRSS":{"type":"number"},"minorPageFault":{"type":"number"},"sharedMemorySize":{"type":"number"},"signalsCount":{"type":"number"},"swappedOut":{"type":"number"},"systemCPUTime":{"type":"number"},"unsharedDataSize":{"type":"number"},"unsharedStackSize":{"type":"number"},"userCPUTime":{"type":"number"},"voluntaryContextSwitches":{"type":"number"}},"nullable":false,"required":["fsRead","fsWrite","involuntaryContextSwitches","ipcReceived","ipcSent","majorPageFault","maxRSS","minorPageFault","sharedMemorySize","signalsCount","swappedOut","systemCPUTime","unsharedDataSize","unsharedStackSize","userCPUTime","voluntaryContextSwitches"]},"IBbsArticle.IStore":{"type":"object","properties":{"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"required":["title","body","files"]},"IAttachmentFile":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"nullable":true},"extension":{"type":"string","maxLength":8,"minLength":1,"nullable":true},"url":{"type":"string","format":"uri"}},"nullable":false,"required":["name","extension","url"]},"IBbsArticle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"required":["id","created_at","title","body","files"]},"PartialIBbsArticle.IStore":{"type":"object","properties":{"title":{"type":"string","maxLength":50,"minLength":3},"body":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/IAttachmentFile"}}},"nullable":false,"description":"Make all properties in T optional"}},"securitySchemes":{"bearer":{"type":"apiKey","in":"header","name":"Authorization"}}}}

test/features/beautify/swagger.json

@@ -7,7 +7,7 @@
     }
   ],
   "info": {
-    "version": "2.5.8",
+    "version": "2.5.11-dev.20240224",
     "title": "@nestia/test",
     "description": "Test program of Nestia",
     "license": {