@nestia/sdk 1.4.12 → 1.4.13-dev.20230726

package/src/generates/SwaggerGenerator.ts

@@ -14,6 +14,8 @@ import { ApplicationProgrammer } from "typia/lib/programmers/ApplicationProgramm
 import { INestiaConfig } from "../INestiaConfig";
 import { IRoute } from "../structures/IRoute";
 import { ISwaggerDocument } from "../structures/ISwaggerDocument";
+import { ISwaggerRoute } from "../structures/ISwaggerRoute";
+import { ISwaggerSecurityScheme } from "../structures/ISwaggerSecurityScheme";
 import { FileRetriever } from "../utils/FileRetriever";
 import { MapUtil } from "../utils/MapUtil";
 
@@ -24,6 +26,9 @@ export namespace SwaggerGenerator {
         async (routeList: IRoute[]): Promise<void> => {
             console.log("Generating Swagger Documents");
 
+            // VALIDATE SECURITY
+            validate_security(config)(routeList);
+
             // PREPARE ASSETS
             const parsed: NodePath.ParsedPath = NodePath.parse(config.output);
             const directory: string = NodePath.dirname(parsed.dir);
@@ -50,12 +55,15 @@ export namespace SwaggerGenerator {
             // CONSTRUCT SWAGGER DOCUMENTS
             const tupleList: Array<ISchemaTuple> = [];
             const swagger: ISwaggerDocument = await initialize(config);
-            const pathDict: Map<string, ISwaggerDocument.IPath> = new Map();
+            const pathDict: Map<
+                string,
+                Record<string, ISwaggerRoute>
+            > = new Map();
 
             for (const route of routeList) {
                 if (route.tags.find((tag) => tag.name === "internal")) continue;
 
-                const path: ISwaggerDocument.IPath = MapUtil.take(
+                const path: Record<string, ISwaggerRoute> = MapUtil.take(
                     pathDict,
                     get_path(route.path, route.parameters),
                     () => ({}),
@@ -95,6 +103,76 @@ export namespace SwaggerGenerator {
             );
         };
 
+    const validate_security =
+        (config: INestiaConfig.ISwaggerConfig) =>
+        (routeList: IRoute[]): void | never => {
+            const securityMap: Map<
+                string,
+                { scheme: ISwaggerSecurityScheme; 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 "${key}" does not exists.`,
+                        );
+                    else if (scopes.length === 0) return;
+                    else if (security.scheme.type !== "oauth2")
+                        return reporter(
+                            `target security "${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 ${key} does not have 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.symbol} at "${route.location}")`,
+                            ),
+                        )(key, scopes);
+
+            if (violations.length)
+                throw new Error(
+                    `Error on NestiaApplication.swagger(): invalid security configuration.\n` +
+                        `\n` +
+                        `List of violations:\n` +
+                        violations.join("\n"),
+                );
+        };
+
     /* ---------------------------------------------------------
         INITIALIZERS
     --------------------------------------------------------- */
@@ -170,7 +248,7 @@ export namespace SwaggerGenerator {
         collection: MetadataCollection,
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
-    ): ISwaggerDocument.IRoute {
+    ): ISwaggerRoute {
         const bodyParam = route.parameters.find(
             (param) => param.category === "body",
         );
@@ -238,6 +316,7 @@ export namespace SwaggerGenerator {
             ),
             summary,
             description,
+            security: route.security.length ? route.security : undefined,
             "x-nestia-namespace": [
                 ...route.path
                     .split("/")
@@ -245,6 +324,7 @@ export namespace SwaggerGenerator {
                 route.name,
             ].join("."),
             "x-nestia-jsDocTags": route.tags,
+            "x-nestia-method": route.method,
         };
     }
 
@@ -262,8 +342,8 @@ export namespace SwaggerGenerator {
     }
 
     function emend_security(
-        input: INestiaConfig.ISwaggerConfig.ISecurityScheme,
-    ): ISwaggerDocument.ISecurityScheme {
+        input: ISwaggerSecurityScheme,
+    ): ISwaggerSecurityScheme {
         if (input.type === "apiKey")
             return {
                 ...input,
@@ -282,7 +362,7 @@ export namespace SwaggerGenerator {
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
         parameter: IRoute.IParameter,
-    ): ISwaggerDocument.IParameter {
+    ): ISwaggerRoute.IParameter {
         const schema: IJsonSchema | null = generate_schema(
             checker,
             collection,
@@ -322,7 +402,7 @@ export namespace SwaggerGenerator {
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
         parameter: IRoute.IParameter,
-    ): ISwaggerDocument.IRequestBody {
+    ): ISwaggerRoute.IRequestBody {
         const schema: IJsonSchema | null = generate_schema(
             checker,
             collection,
@@ -362,7 +442,7 @@ export namespace SwaggerGenerator {
         collection: MetadataCollection,
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
-    ): ISwaggerDocument.IResponseBody {
+    ): ISwaggerRoute.IResponseBody {
         // OUTPUT WITH SUCCESS STATUS
         const status: string =
             route.status !== undefined
@@ -376,7 +456,7 @@ export namespace SwaggerGenerator {
             tupleList,
             route.output.type,
         );
-        const success: ISwaggerDocument.IResponseBody = {
+        const success: ISwaggerRoute.IResponseBody = {
             [status]: {
                 description:
                     warning.get(route.encrypted).get("response", route.method) +
@@ -396,7 +476,7 @@ export namespace SwaggerGenerator {
         };
 
         // EXCEPTION STATUSES
-        const exceptions: ISwaggerDocument.IResponseBody = Object.fromEntries(
+        const exceptions: ISwaggerRoute.IResponseBody = Object.fromEntries(
             route.tags
                 .filter(
                     (tag) =>

package/src/structures/IController.ts

@@ -5,6 +5,7 @@ export interface IController {
     name: string;
     paths: string[];
     functions: IController.IFunction[];
+    security: Record<string, string[]>[];
 }
 
 export namespace IController {
@@ -17,6 +18,7 @@ export namespace IController {
         status?: number;
         type?: string;
         contentType: "application/json" | "text/plain";
+        security: Record<string, string[]>[];
     }
 
     export type IParameter =

package/src/structures/IRoute.ts

@@ -23,6 +23,7 @@ export interface IRoute {
         | { type: "setter"; source: string; target?: string }
         | { type: "assigner"; source: string }
     >;
+    security: Record<string, string[]>[];
 }
 
 export namespace IRoute {

package/src/structures/ISwaggerComponents.ts

@@ -0,0 +1,29 @@
+import { IJsonComponents } from "typia";
+
+import { ISwaggerSecurityScheme } from "./ISwaggerSecurityScheme";
+
+/**
+ * Reusable components in Swagger.
+ *
+ * `ISwaggerComponents` is a data structure representing content of `components` object
+ * in `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 ISwaggerComponents {
+    /**
+     * An object to hold reusable DTO schemas.
+     *
+     * For reference, `nestia` stores every object and alias types as reusable DTO
+     * schemas. The alias type means that defined by `type` keyword in TypeScript.
+     */
+    schemas?: Record<string, IJsonComponents.IObject | IJsonComponents.IAlias>;
+
+    /**
+     * An object to hold reusable security schemes.
+     *
+     * This property be configured by user in `nestia.config.ts` file.
+     */
+    securitySchemes?: Record<string, ISwaggerSecurityScheme>;
+}

package/src/structures/ISwaggerDocument.ts

@@ -1,124 +1,96 @@
-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 namespace ISwaggerDocument {
+    /**
+     * Remote server definition.
+     */
     export 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.
+     */
     export interface IInfo {
+        /**
+         * Version of the API.
+         */
         version: string;
-        title: string;
-        description?: string;
-    }
 
-    export interface IComponents extends IJsonComponents {
-        securitySchemes?: Record<string, ISecurityScheme>;
-    }
-
-    /* ---------------------------------------------------------
-        SECURITY SCHEMES
-    --------------------------------------------------------- */
-    export type ISecurityScheme =
-        | ISecurityScheme.IHttpBasic
-        | ISecurityScheme.IHttpBearer
-        | ISecurityScheme.IApiKey
-        | ISecurityScheme.IOpenId
-        | ISecurityScheme.IOAuth2;
-    export namespace ISecurityScheme {
-        export interface IHttpBasic {
-            type: "http";
-            schema: "basic";
-        }
-        export interface IHttpBearer {
-            type: "http";
-            scheme: "bearer";
-            bearerFormat?: string;
-        }
-        export interface IApiKey {
-            type: "apiKey";
-            in: "header" | "query" | "cookie";
-            name: string;
-        }
-
-        export interface IOpenId {
-            type: "openIdConnect";
-            openIdConnectUrl: string;
-        }
-
-        export interface IOAuth2 {
-            type: "oauth2";
-            flows: IOAuth2.IFlowSet;
-            description?: string;
-        }
-        export namespace IOAuth2 {
-            export interface IFlowSet {
-                authorizationCode?: IFlow;
-                implicit?: Omit<IFlow, "tokenUrl">;
-                password?: Omit<IFlow, "authorizationUrl">;
-                clientCredentials?: Omit<IFlow, "authorizationUrl">;
-            }
-            export interface IFlow {
-                authorizationUrl: string;
-                tokenUrl: string;
-                refreshUrl: string;
-                scopes?: Record<string, string>;
-            }
-        }
-    }
+        /**
+         * The title of the API.
+         */
+        title: string;
 
-    /* ---------------------------------------------------------
-        ROUTE FUNCTIONS
-    --------------------------------------------------------- */
-    export type IPath = Record<string, IRoute>;
-    export interface IRoute {
-        deprecated?: boolean;
-        tags: string[];
-        parameters: IParameter[];
-        requestBody?: IRequestBody;
-        responses: IResponseBody;
-        summary?: string;
+        /**
+         * A short description of the API.
+         */
         description?: string;
-        "x-nestia-namespace": string;
-        "x-nestia-jsDocTags": IJsDocTagInfo[];
-    }
-
-    export interface IParameter {
-        name: string;
-        in: string;
-        schema: IJsonSchema;
-        required: boolean;
-        description: string;
-    }
-    export interface IRequestBody {
-        description: string;
-        content: IJsonContent;
-        required: true;
-        "x-nestia-encrypted": boolean;
-    }
-    export type IResponseBody = Record<
-        string,
-        {
-            description: string;
-            content?: IJsonContent;
-            "x-nestia-encrypted"?: boolean;
-        }
-    >;
-    export interface IJsonContent {
-        "application/json"?: {
-            schema: IJsonSchema;
-        };
-        "text/plain"?: {
-            schema: IJsonSchema;
-        };
     }
 }

package/src/structures/ISwaggerRoute.ts

@@ -0,0 +1,47 @@
+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 namespace ISwaggerRoute {
+    export interface IParameter {
+        name: string;
+        in: string;
+        schema: IJsonSchema;
+        required: boolean;
+        description: string;
+    }
+    export interface IRequestBody {
+        description: string;
+        content: IContent;
+        required: true;
+        "x-nestia-encrypted": boolean;
+    }
+    export type IResponseBody = Record<
+        string,
+        {
+            description: string;
+            content?: IContent;
+            "x-nestia-encrypted"?: boolean;
+        }
+    >;
+    export interface IContent {
+        "application/json"?: {
+            schema: IJsonSchema;
+        };
+        "text/plain"?: {
+            schema: IJsonSchema;
+        };
+    }
+}

package/src/structures/ISwaggerSecurityScheme.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 namespace ISwaggerSecurityScheme {
+    export interface IHttpBasic {
+        type: "http";
+        schema: "basic";
+    }
+    export interface IHttpBearer {
+        type: "http";
+        scheme: "bearer";
+        bearerFormat?: string;
+    }
+    export interface IApiKey {
+        type: "apiKey";
+        in?: "header" | "query" | "cookie";
+        name?: string;
+    }
+
+    export interface IOpenId {
+        type: "openIdConnect";
+        openIdConnectUrl: string;
+    }
+
+    export interface IOAuth2 {
+        type: "oauth2";
+        flows: IOAuth2.IFlowSet;
+        description?: string;
+    }
+    export namespace IOAuth2 {
+        export interface IFlowSet {
+            authorizationCode?: IFlow;
+            implicit?: Omit<IFlow, "tokenUrl">;
+            password?: Omit<IFlow, "authorizationUrl">;
+            clientCredentials?: Omit<IFlow, "authorizationUrl">;
+        }
+        export interface IFlow {
+            authorizationUrl: string;
+            tokenUrl: string;
+            refreshUrl: string;
+            scopes?: Record<string, string>;
+        }
+    }
+}