@nestia/sdk 1.0.1 → 1.0.2

package/src/generates/SwaggerGenerator.ts

@@ -12,13 +12,13 @@ import { ApplicationProgrammer } from "typia/lib/programmers/ApplicationProgramm
 
 import { INestiaConfig } from "../INestiaConfig";
 import { IRoute } from "../structures/IRoute";
-import { ISwagger } from "../structures/ISwagger";
+import { ISwaggerDocument } from "../structures/ISwaggerDocument";
 import { MapUtil } from "../utils/MapUtil";
 
 export namespace SwaggerGenerator {
     export async function generate(
         checker: ts.TypeChecker,
-        config: INestiaConfig.ISwagger,
+        config: INestiaConfig.ISwaggerConfig,
         routeList: IRoute[],
     ): Promise<void> {
         // PREPARE ASSETS
@@ -33,11 +33,11 @@ export namespace SwaggerGenerator {
 
         // CONSTRUCT SWAGGER DOCUMENTS
         const tupleList: Array<ISchemaTuple> = [];
-        const swagger: ISwagger = await initialize(location);
-        const pathDict: Map<string, ISwagger.IPath> = new Map();
+        const swagger: ISwaggerDocument = await initialize(location);
+        const pathDict: Map<string, ISwaggerDocument.IPath> = new Map();
 
         for (const route of routeList) {
-            const path: ISwagger.IPath = MapUtil.take(
+            const path: ISwaggerDocument.IPath = MapUtil.take(
                 pathDict,
                 get_path(route.path, route.parameters),
                 () => ({}),
@@ -62,13 +62,16 @@ export namespace SwaggerGenerator {
             },
         );
         swagger.components = {
-            ...(swagger.components || {}),
+            ...(swagger.components ?? {}),
             schemas: application.components.schemas,
         };
         tupleList.forEach(({ schema }, index) => {
             Object.assign(schema, application.schemas[index]!);
         });
 
+        // CONFIGURE SECURITY
+        if (config.security) fill_security(config.security, swagger);
+
         // ERASE IJsonComponents.IObject.$id
         for (const obj of Object.values(swagger.components.schemas))
             if (obj.$id) delete obj.$id;
@@ -84,9 +87,9 @@ export namespace SwaggerGenerator {
     /* ---------------------------------------------------------
         INITIALIZERS
     --------------------------------------------------------- */
-    async function initialize(path: string): Promise<ISwagger> {
+    async function initialize(path: string): Promise<ISwaggerDocument> {
         // LOAD OR CREATE NEW SWAGGER DATA
-        const swagger: ISwagger = fs.existsSync(path)
+        const swagger: ISwaggerDocument = fs.existsSync(path)
             ? JSON.parse(await fs.promises.readFile(path, "utf8"))
             : {
                   openapi: "3.0.1",
@@ -122,7 +125,7 @@ export namespace SwaggerGenerator {
         collection: MetadataCollection,
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
-    ): ISwagger.IRoute {
+    ): ISwaggerDocument.IRoute {
         const bodyParam = route.parameters.find(
             (param) => param.category === "body",
         );
@@ -170,9 +173,35 @@ export namespace SwaggerGenerator {
                 route,
             ),
             description: CommentFactory.generate(route.comments),
+            "x-nestia-jsDocTags": route.tags,
         };
     }
 
+    function fill_security(
+        security: Required<INestiaConfig.ISwaggerConfig>["security"],
+        swagger: ISwaggerDocument,
+    ): void {
+        swagger.security ??= [];
+        swagger.components.securitySchemes = {};
+
+        for (const [key, value] of Object.entries(security)) {
+            swagger.security.push(key);
+            swagger.components.securitySchemes[key] = emend_security(value);
+        }
+    }
+
+    function emend_security(
+        input: INestiaConfig.ISwaggerConfig.ISecurityScheme,
+    ): ISwaggerDocument.ISecurityScheme {
+        if (input.type === "apiKey")
+            return {
+                ...input,
+                in: input.in ?? "header",
+                name: input.name ?? "Authorization",
+            };
+        return input;
+    }
+
     /* ---------------------------------------------------------
         REQUEST & RESPONSE
     --------------------------------------------------------- */
@@ -182,7 +211,7 @@ export namespace SwaggerGenerator {
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
         parameter: IRoute.IParameter,
-    ): ISwagger.IParameter {
+    ): ISwaggerDocument.IParameter {
         const schema: IJsonSchema | null = generate_schema(
             checker,
             collection,
@@ -195,7 +224,7 @@ export namespace SwaggerGenerator {
             );
 
         return {
-            name: parameter.field || parameter.name,
+            name: parameter.field ?? parameter.name,
             in: parameter.category === "param" ? "path" : parameter.category,
             description:
                 get_parametric_description(route, "param", parameter.name) ||
@@ -211,7 +240,7 @@ export namespace SwaggerGenerator {
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
         parameter: IRoute.IParameter,
-    ): ISwagger.IRequestBody {
+    ): ISwaggerDocument.IRequestBody {
         const schema: IJsonSchema | null = generate_schema(
             checker,
             collection,
@@ -226,7 +255,7 @@ export namespace SwaggerGenerator {
         return {
             description:
                 warning.get(parameter.encrypted).get("request") +
-                (get_parametric_description(route, "param", parameter.name) ||
+                (get_parametric_description(route, "param", parameter.name) ??
                     ""),
             content: {
                 "application/json": {
@@ -242,7 +271,7 @@ export namespace SwaggerGenerator {
         collection: MetadataCollection,
         tupleList: Array<ISchemaTuple>,
         route: IRoute,
-    ): ISwagger.IResponseBody {
+    ): ISwaggerDocument.IResponseBody {
         // OUTPUT WITH SUCCESS STATUS
         const status: string =
             route.method === "GET" || route.method === "DELETE" ? "200" : "201";
@@ -252,12 +281,12 @@ export namespace SwaggerGenerator {
             tupleList,
             route.output.type,
         );
-        const success: ISwagger.IResponseBody = {
+        const success: ISwaggerDocument.IResponseBody = {
             [status]: {
                 description:
                     warning.get(route.encrypted).get("response", route.method) +
-                    (get_parametric_description(route, "return") ||
-                        get_parametric_description(route, "returns") ||
+                    (get_parametric_description(route, "return") ??
+                        get_parametric_description(route, "returns") ??
                         ""),
                 content:
                     schema === null || route.output.name === "void"
@@ -271,7 +300,7 @@ export namespace SwaggerGenerator {
         };
 
         // EXCEPTION STATUSES
-        const exceptions: ISwagger.IResponseBody = Object.fromEntries(
+        const exceptions: ISwaggerDocument.IResponseBody = Object.fromEntries(
             route.tags
                 .filter(
                     (tag) =>

package/src/structures/IRoute.ts

@@ -16,6 +16,10 @@ export interface IRoute {
     symbol: string;
     comments: ts.SymbolDisplayPart[];
     tags: ts.JSDocTagInfo[];
+    setHeaders: Array<
+        | { type: "setter"; source: string; target?: string }
+        | { type: "assigner"; source: string }
+    >;
 }
 
 export namespace IRoute {

package/src/structures/ISwaggerDocument.ts

@@ -0,0 +1,117 @@
+import { IJsonComponents, IJsonSchema } from "typia";
+import { IJsDocTagInfo } from "typia/lib/metadata/IJsDocTagInfo";
+
+export interface ISwaggerDocument {
+    openapi: "3.0";
+    servers: ISwaggerDocument.IServer[];
+    info: ISwaggerDocument.IInfo;
+    components: ISwaggerDocument.IComponents;
+    security?: string[];
+    paths: Record<string, ISwaggerDocument.IPath>;
+}
+export namespace ISwaggerDocument {
+    export interface IServer {
+        url: string;
+        description?: string;
+    }
+
+    export interface IInfo {
+        version: string;
+        title: 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>;
+            }
+        }
+    }
+
+    /* ---------------------------------------------------------
+        ROUTE FUNCTIONS
+    --------------------------------------------------------- */
+    export type IPath = Record<string, IRoute>;
+    export interface IRoute {
+        tags: string[];
+        parameters: IParameter[];
+        requestBody?: IRequestBody;
+        responses: IResponseBody;
+        summary?: string;
+        description: string;
+        security?: string[];
+        "x-nestia-jsDocTags": IJsDocTagInfo[];
+    }
+
+    export interface IParameter {
+        name: string;
+        in: string;
+        schema: IJsonSchema;
+        required: true;
+        description: string;
+    }
+    export interface IRequestBody {
+        description: string;
+        content: IJsonContent;
+        required: true;
+    }
+    export type IResponseBody = Record<
+        string,
+        {
+            description: string;
+            content?: IJsonContent;
+        }
+    >;
+    export interface IJsonContent {
+        "application/json": {
+            schema: IJsonSchema;
+        };
+    }
+}

package/lib/structures/ISwagger.d.ts

@@ -1,48 +0,0 @@
-import { IJsonComponents, IJsonSchema } from "typia";
-export interface ISwagger {
-    openapi: "3.0";
-    servers: ISwagger.IServer[];
-    info: ISwagger.IInfo;
-    paths: Record<string, ISwagger.IPath>;
-    components: IJsonComponents;
-}
-export declare namespace ISwagger {
-    type IPath = Record<string, IRoute>;
-    interface IRoute {
-        description: string;
-        tags: string[];
-        parameters: IParameter[];
-        responses: IResponseBody;
-        requestBody?: IRequestBody;
-        summary?: string;
-    }
-    interface IInfo {
-        version: string;
-        title: string;
-    }
-    interface IParameter {
-        name: string;
-        in: string;
-        schema: IJsonSchema;
-        required: true;
-        description: string;
-    }
-    interface IRequestBody {
-        description: string;
-        content: IJsonContent;
-        required: true;
-    }
-    type IResponseBody = Record<string, {
-        description: string;
-        content?: IJsonContent;
-    }>;
-    interface IServer {
-        url: string;
-        description?: string;
-    }
-    interface IJsonContent {
-        "application/json": {
-            schema: IJsonSchema;
-        };
-    }
-}

package/lib/structures/ISwagger.js.map

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

package/src/structures/ISwagger.ts

@@ -1,55 +0,0 @@
-import { IJsonComponents, IJsonSchema } from "typia";
-
-export interface ISwagger {
-    openapi: "3.0";
-    servers: ISwagger.IServer[];
-    info: ISwagger.IInfo;
-    paths: Record<string, ISwagger.IPath>;
-    components: IJsonComponents;
-}
-export namespace ISwagger {
-    export type IPath = Record<string, IRoute>;
-    export interface IRoute {
-        description: string;
-        tags: string[];
-        parameters: IParameter[];
-        responses: IResponseBody;
-        requestBody?: IRequestBody;
-        summary?: string;
-    }
-
-    export interface IInfo {
-        version: string;
-        title: string;
-    }
-    export interface IParameter {
-        name: string;
-        in: string;
-        schema: IJsonSchema;
-        required: true;
-        description: string;
-    }
-    export interface IRequestBody {
-        description: string;
-        content: IJsonContent;
-        required: true;
-    }
-    export type IResponseBody = Record<
-        string,
-        {
-            description: string;
-            content?: IJsonContent;
-        }
-    >;
-
-    export interface IServer {
-        url: string;
-        description?: string;
-    }
-
-    export interface IJsonContent {
-        "application/json": {
-            schema: IJsonSchema;
-        };
-    }
-}