@nestia/sdk 1.4.12 → 1.4.13-dev.20230726-2

package/lib/structures/ISwaggerDocument.d.ts

@@ -1,102 +1,86 @@
-import { IJsonComponents, IJsonSchema } from "typia";
-import { IJsDocTagInfo } from "typia/lib/metadata/IJsDocTagInfo";
+import { ISwaggerComponents } from "./ISwaggerComponents";
+import { ISwaggerRoute } from "./ISwaggerRoute";
+/**
+ * Swagger Document.
+ *
+ * `ISwaggerDocument` is a data structure representing content of `swagger.json` file
+ * generated by Nestia. Note that, this is not an universal structure, but a dedicated
+ * structure only for Nestia.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface ISwaggerDocument {
-    openapi: "3.0.1";
+    /**
+     * The version of the OpenAPI document.
+     *
+     * Nestia always generate OpenAPI 3.0.x document.
+     */
+    openapi: `3.0.${number}`;
+    /**
+     * List of servers that provide the API.
+     */
     servers: ISwaggerDocument.IServer[];
+    /**
+     * Information about the API.
+     */
     info: ISwaggerDocument.IInfo;
-    components: ISwaggerDocument.IComponents;
+    /**
+     * The available paths and operations for the API.
+     *
+     * The 1st key is the path, and the 2nd key is the HTTP method.
+     */
+    paths: Record<string, Record<string, ISwaggerRoute>>;
+    /**
+     * An object to hold reusable data structures.
+     *
+     * It stores both DTO schemas and security schemes.
+     *
+     * For reference, `nestia` defines every object and alias types as reusable DTO
+     * schemas. The alias type means that defined by `type` keyword in TypeScript.
+     */
+    components: ISwaggerComponents;
+    /**
+     * A declaration of which security mechanisms can be used across the API.
+     *
+     * When this property be configured, it would be overwritten in every API routes.
+     *
+     * For reference, key means the name of security scheme and value means the `scopes`.
+     * The `scopes` can be used only when target security scheme is `oauth2` type,
+     * especially for {@link ISwaggerSecurityScheme.IOAuth2.IFlow.scopes} property.
+     */
     security?: Record<string, string[]>[];
-    paths: Record<string, ISwaggerDocument.IPath>;
 }
 export declare namespace ISwaggerDocument {
+    /**
+     * Remote server definition.
+     */
     interface IServer {
+        /**
+         * A URL to the target host.
+         *
+         * @format url
+         */
         url: string;
+        /**
+         * An optional string describing the target server.
+         */
         description?: string;
     }
+    /**
+     * General information about the API.
+     */
     interface IInfo {
+        /**
+         * Version of the API.
+         */
         version: string;
+        /**
+         * The title of the API.
+         */
         title: string;
+        /**
+         * A short description of the API.
+         */
         description?: string;
     }
-    interface IComponents extends IJsonComponents {
-        securitySchemes?: Record<string, ISecurityScheme>;
-    }
-    type ISecurityScheme = ISecurityScheme.IHttpBasic | ISecurityScheme.IHttpBearer | ISecurityScheme.IApiKey | ISecurityScheme.IOpenId | ISecurityScheme.IOAuth2;
-    namespace ISecurityScheme {
-        interface IHttpBasic {
-            type: "http";
-            schema: "basic";
-        }
-        interface IHttpBearer {
-            type: "http";
-            scheme: "bearer";
-            bearerFormat?: string;
-        }
-        interface IApiKey {
-            type: "apiKey";
-            in: "header" | "query" | "cookie";
-            name: string;
-        }
-        interface IOpenId {
-            type: "openIdConnect";
-            openIdConnectUrl: string;
-        }
-        interface IOAuth2 {
-            type: "oauth2";
-            flows: IOAuth2.IFlowSet;
-            description?: string;
-        }
-        namespace IOAuth2 {
-            interface IFlowSet {
-                authorizationCode?: IFlow;
-                implicit?: Omit<IFlow, "tokenUrl">;
-                password?: Omit<IFlow, "authorizationUrl">;
-                clientCredentials?: Omit<IFlow, "authorizationUrl">;
-            }
-            interface IFlow {
-                authorizationUrl: string;
-                tokenUrl: string;
-                refreshUrl: string;
-                scopes?: Record<string, string>;
-            }
-        }
-    }
-    type IPath = Record<string, IRoute>;
-    interface IRoute {
-        deprecated?: boolean;
-        tags: string[];
-        parameters: IParameter[];
-        requestBody?: IRequestBody;
-        responses: IResponseBody;
-        summary?: string;
-        description?: string;
-        "x-nestia-namespace": string;
-        "x-nestia-jsDocTags": IJsDocTagInfo[];
-    }
-    interface IParameter {
-        name: string;
-        in: string;
-        schema: IJsonSchema;
-        required: boolean;
-        description: string;
-    }
-    interface IRequestBody {
-        description: string;
-        content: IJsonContent;
-        required: true;
-        "x-nestia-encrypted": boolean;
-    }
-    type IResponseBody = Record<string, {
-        description: string;
-        content?: IJsonContent;
-        "x-nestia-encrypted"?: boolean;
-    }>;
-    interface IJsonContent {
-        "application/json"?: {
-            schema: IJsonSchema;
-        };
-        "text/plain"?: {
-            schema: IJsonSchema;
-        };
-    }
 }

package/lib/structures/ISwaggerRoute.d.ts

@@ -0,0 +1,43 @@
+import { IJsonSchema } from "typia";
+import { IJsDocTagInfo } from "typia/lib/metadata/IJsDocTagInfo";
+export interface ISwaggerRoute {
+    deprecated?: boolean;
+    security?: Record<string, string[]>[];
+    tags: string[];
+    parameters: ISwaggerRoute.IParameter[];
+    requestBody?: ISwaggerRoute.IRequestBody;
+    responses: ISwaggerRoute.IResponseBody;
+    summary?: string;
+    description?: string;
+    "x-nestia-method": string;
+    "x-nestia-namespace": string;
+    "x-nestia-jsDocTags": IJsDocTagInfo[];
+}
+export declare namespace ISwaggerRoute {
+    interface IParameter {
+        name: string;
+        in: string;
+        schema: IJsonSchema;
+        required: boolean;
+        description: string;
+    }
+    interface IRequestBody {
+        description: string;
+        content: IContent;
+        required: true;
+        "x-nestia-encrypted": boolean;
+    }
+    type IResponseBody = Record<string, {
+        description: string;
+        content?: IContent;
+        "x-nestia-encrypted"?: boolean;
+    }>;
+    interface IContent {
+        "application/json"?: {
+            schema: IJsonSchema;
+        };
+        "text/plain"?: {
+            schema: IJsonSchema;
+        };
+    }
+}

package/lib/structures/ISwaggerRoute.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerRoute.js.map

package/lib/structures/ISwaggerRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerRoute.js","sourceRoot":"","sources":["../../src/structures/ISwaggerRoute.ts"],"names":[],"mappings":""}

package/lib/structures/ISwaggerSecurityScheme.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Security schema of Swagger Documents.
+ *
+ * `ISwaggerSecurityScheme` is a data structure representing content of
+ * `securitySchemes` in `swagger.json` file. It is composed with 5 types of security
+ * schemes as an union type like below.
+ *
+ * @reference https://swagger.io/specification/#security-scheme-object
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ISwaggerSecurityScheme = ISwaggerSecurityScheme.IHttpBasic | ISwaggerSecurityScheme.IHttpBearer | ISwaggerSecurityScheme.IApiKey | ISwaggerSecurityScheme.IOpenId | ISwaggerSecurityScheme.IOAuth2;
+export declare namespace ISwaggerSecurityScheme {
+    interface IHttpBasic {
+        type: "http";
+        schema: "basic";
+    }
+    interface IHttpBearer {
+        type: "http";
+        scheme: "bearer";
+        bearerFormat?: string;
+    }
+    interface IApiKey {
+        type: "apiKey";
+        in?: "header" | "query" | "cookie";
+        name?: string;
+    }
+    interface IOpenId {
+        type: "openIdConnect";
+        openIdConnectUrl: string;
+    }
+    interface IOAuth2 {
+        type: "oauth2";
+        flows: IOAuth2.IFlowSet;
+        description?: string;
+    }
+    namespace IOAuth2 {
+        interface IFlowSet {
+            authorizationCode?: IFlow;
+            implicit?: Omit<IFlow, "tokenUrl">;
+            password?: Omit<IFlow, "authorizationUrl">;
+            clientCredentials?: Omit<IFlow, "authorizationUrl">;
+        }
+        interface IFlow {
+            authorizationUrl: string;
+            tokenUrl: string;
+            refreshUrl: string;
+            scopes?: Record<string, string>;
+        }
+    }
+}

package/lib/structures/ISwaggerSecurityScheme.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerSecurityScheme.js.map

package/lib/structures/ISwaggerSecurityScheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerSecurityScheme.js","sourceRoot":"","sources":["../../src/structures/ISwaggerSecurityScheme.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "1.4.12",
+  "version": "1.4.13-dev.20230726-2",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -35,15 +35,16 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^1.4.0",
+    "@nestia/fetcher": ">= 1.4.0",
     "cli": "^1.0.1",
     "glob": "^7.2.0",
     "path-to-regexp": "^6.2.1",
+    "reflect-metadata": ">= 0.1.12",
     "tgrid": "^0.8.7",
     "tsconfck": "^2.0.1",
     "tsconfig-paths": "^4.1.1",
     "tstl": "^2.5.13",
-    "typia": "^4.1.6"
+    "typia": "^4.1.8"
   },
   "peerDependencies": {
     "@nestia/fetcher": ">= 1.4.0",

package/src/INestiaConfig.ts

@@ -1,6 +1,7 @@
 import type ts from "typescript";
 
 import type { ISwaggerDocument } from "./structures/ISwaggerDocument";
+import { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme";
 import type { StripEnums } from "./utils/StripEnums";
 
 /**
@@ -178,28 +179,11 @@ export namespace INestiaConfig {
 
         /**
          * Security schemes.
+         *
+         * When generating `swagger.json` file through `nestia`, if your controllers or
+         * theirs methods have a security key which is not enrolled in here property,
+         * it would be an error.
          */
-        security?: Record<string, ISwaggerConfig.ISecurityScheme>;
-    }
-    export namespace ISwaggerConfig {
-        export type ISecurityScheme =
-            | IApiKey
-            | Exclude<
-                  ISwaggerDocument.ISecurityScheme,
-                  ISwaggerDocument.ISecurityScheme.IApiKey
-              >;
-        export interface IApiKey {
-            type: "apiKey";
-
-            /**
-             * @default header
-             */
-            in?: "header" | "query" | "cookie";
-
-            /**
-             * @default Authorization
-             */
-            name?: string;
-        }
+        security?: Record<string, ISwaggerSecurityScheme>;
     }
 }

package/src/NestiaSdkApplication.ts

@@ -210,6 +210,18 @@ export class NestiaSdkApplication {
             routeList.push(...ControllerAnalyzer.analyze(checker, file, c));
         }
 
+        // FIND IMPLICIT TYPES
+        const implicit: IRoute[] = routeList.filter(is_implicit_return_typed);
+        if (implicit.length > 0)
+            throw new Error(
+                `NestiaApplication.${method}(): implicit return type is not allowed.\n` +
+                    "\n" +
+                    "List of implicit return typed routes:\n" +
+                    implicit
+                        .map((it) => `  - ${it.symbol} at "${it.location}"`)
+                        .join("\n"),
+            );
+
         // DO GENERATE
         AccessorAnalyzer.analyze(routeList);
         await archiver(checker)(config(this.config_))(routeList);
@@ -273,3 +285,20 @@ const title = (str: string): void => {
     console.log(` ${str}`);
     console.log("-----------------------------------------------------------");
 };
+
+const is_implicit_return_typed = (route: IRoute): boolean => {
+    const name: string = route.output.name;
+    if (name === "void") return false;
+    else if (name.indexOf("readonly [") !== -1) return true;
+
+    const pos: number = name.indexOf("__object");
+    if (pos === -1) return false;
+
+    const before: number = pos - 1;
+    const after: number = pos + "__object".length;
+    for (const i of [before, after])
+        if (name[i] === undefined) continue;
+        else if (VARIABLE.test(name[i])) return false;
+    return true;
+};
+const VARIABLE = /[a-zA-Z_$0-9]/;

package/src/analyses/ControllerAnalyzer.ts

@@ -10,6 +10,7 @@ import { PathUtil } from "../utils/PathUtil";
 import { GenericAnalyzer } from "./GenericAnalyzer";
 import { ImportAnalyzer } from "./ImportAnalyzer";
 import { PathAnalyzer } from "./PathAnalyzer";
+import { SecurityAnalyzer } from "./SecurityAnalyzer";
 
 export namespace ControllerAnalyzer {
     export function analyze(
@@ -134,8 +135,29 @@ export namespace ControllerAnalyzer {
             .toJSON()
             .map((pair) => [pair.first, pair.second.toJSON()]);
 
-        // CONSTRUCT COMMON DATA
+        // PARSE COMMENT TAGS
         const tags = signature.getJsDocTags();
+        const security: Record<string, string[]>[] = SecurityAnalyzer.merge(
+            ...controller.security,
+            ...func.security,
+            ...tags
+                .filter((tag) => tag.name === "security")
+                .map((tag) =>
+                    (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(),
+        );
+
+        // CONSTRUCT COMMON DATA
         const common: Omit<IRoute, "path" | "accessors"> = {
             ...func,
             parameters,
@@ -168,6 +190,7 @@ export namespace ControllerAnalyzer {
                               source: t.text![0].text,
                           },
                 ),
+            security,
         };
 
         // CONFIGURE PATHS

package/src/analyses/ReflectAnalyzer.ts

@@ -1,12 +1,12 @@
 import * as Constants from "@nestjs/common/constants";
+import "reflect-metadata";
 import { equal } from "tstl/ranges/module";
 
 import { IController } from "../structures/IController";
 import { ParamCategory } from "../structures/ParamCategory";
 import { ArrayUtil } from "../utils/ArrayUtil";
 import { PathAnalyzer } from "./PathAnalyzer";
-
-declare const Reflect: any;
+import { SecurityAnalyzer } from "./SecurityAnalyzer";
 
 type IModule = {
     [key: string]: any;
@@ -89,6 +89,7 @@ export namespace ReflectAnalyzer {
             name,
             paths,
             functions: [],
+            security: _Get_security(creator),
         };
 
         // PARSE CHILDREN DATA
@@ -125,6 +126,12 @@ export namespace ReflectAnalyzer {
         else return value;
     }
 
+    function _Get_security(value: any): Record<string, string[]>[] {
+        const entire: Record<string, string[]>[] | undefined =
+            Reflect.getMetadata("swagger/apiSecurity", value);
+        return entire ? SecurityAnalyzer.merge(...entire) : [];
+    }
+
     /* ---------------------------------------------------------
         FUNCTION
     --------------------------------------------------------- */
@@ -173,6 +180,7 @@ export namespace ReflectAnalyzer {
                         typeof h?.value === "string" &&
                         h.name.toLowerCase() === "content-type",
                 )?.value ?? "application/json",
+            security: _Get_security(proto),
         };
 
         // PARSE CHILDREN DATA

package/src/analyses/SecurityAnalyzer.ts

@@ -0,0 +1,20 @@
+import { MapUtil } from "../utils/MapUtil";
+
+export namespace SecurityAnalyzer {
+    export const merge = (...entire: Record<string, string[]>[]) => {
+        const dict: Map<string, Set<string>> = new Map();
+        for (const obj of entire)
+            for (const [key, value] of Object.entries(obj)) {
+                const set = MapUtil.take(dict, key, () => new Set());
+                for (const val of value) set.add(val);
+            }
+        const output: Record<string, string[]>[] = [];
+        for (const [key, set] of dict) {
+            const obj = {
+                [key]: [...set],
+            };
+            output.push(obj);
+        }
+        return output;
+    };
+}

package/src/generates/SdkGenerator.ts

@@ -13,18 +13,6 @@ export namespace SdkGenerator {
         async (routes: IRoute[]): Promise<void> => {
             console.log("Generating SDK Library");
 
-            // FIND IMPLICIT TYPES
-            const implicit: IRoute[] = routes.filter(is_implicit_return_typed);
-            if (implicit.length > 0)
-                throw new Error(
-                    "NestiaApplication.sdk(): implicit return type is not allowed.\n" +
-                        "\n" +
-                        "List of implicit return typed routes:\n" +
-                        implicit
-                            .map((it) => `  - ${it.symbol} at "${it.location}"`)
-                            .join("\n"),
-                );
-
             // PREPARE NEW DIRECTORIES
             try {
                 await fs.promises.mkdir(config.output!);
@@ -85,23 +73,6 @@ export namespace SdkGenerator {
     );
 }
 
-const is_implicit_return_typed = (route: IRoute): boolean => {
-    const name: string = route.output.name;
-    if (name === "void") return false;
-    else if (name.indexOf("readonly [") !== -1) return true;
-
-    const pos: number = name.indexOf("__object");
-    if (pos === -1) return false;
-
-    const before: number = pos - 1;
-    const after: number = pos + "__object".length;
-    for (const i of [before, after])
-        if (name[i] === undefined) continue;
-        else if (VARIABLE.test(name[i])) return false;
-    return true;
-};
-const VARIABLE = /[a-zA-Z_$0-9]/;
-
 const BUNDLE_CHANGES: Record<string, [string, string][]> = {
     "IConnection.ts": [
         [