@grandlinex/swagger-mate 1.3.1 → 1.3.3

package/dist/mjs/Swagger/Path/ESchemaEditor.js

@@ -0,0 +1,147 @@
+import { getColumnMeta, getEntityMeta, } from '@grandlinex/core';
+function resolveDBType(dType) {
+    switch (dType) {
+        case 'int':
+        case 'long':
+            return 'integer';
+        case 'double':
+        case 'float':
+            return 'number';
+        case 'blob':
+            return 'string';
+        case 'string':
+        case 'text':
+        case 'uuid':
+            return 'string';
+        case 'boolean':
+            return 'boolean';
+        case 'date':
+            return 'string';
+        case 'json':
+            return 'object';
+        default:
+            throw Error('TypeNotSupported');
+    }
+}
+export class ESchemaEditor {
+    constructor(entity, name) {
+        this.data = ESchemaEditor.schemaFromEntity(entity);
+        this.name = name;
+    }
+    /**
+     * Removes the specified keys from the schema's properties and updates the required list.
+     *
+     * @param {...(keyof T)} keys - The keys of the properties to remove.
+     * @returns {ESchemaEditor<T>} The editor instance for method chaining.
+     */
+    remove(...keys) {
+        if (this.data.properties) {
+            for (const key of keys) {
+                this.data.properties = Object.fromEntries(Object.entries(this.data.properties).filter(([e]) => key !== e));
+                this.data.required = (this.data.required || []).filter((e) => key !== e);
+            }
+        }
+        return this;
+    }
+    /**
+     * Adds properties to the schema based on the provided options.
+     *
+     * @param {...ESchemaAddOption} options The options describing the properties to add. Each option may specify a
+     *   `key`, a `schema` or an `entity`, and optionally whether the property is a `list`, `nullable`, or `required`.
+     * @returns {ESchemaEditor<T>} The editor instance for chaining.
+     */
+    add(...options) {
+        if (!this.data.properties) {
+            return this;
+        }
+        for (const option of options) {
+            if (option.schema) {
+                if (option.list) {
+                    this.data.properties[option.key] = {
+                        type: 'array',
+                        items: option.schema,
+                        nullable: option.nullable,
+                    };
+                }
+                else {
+                    this.data.properties[option.key] = option.schema;
+                }
+            }
+            else if (option.entity) {
+                const scheme = ESchemaEditor.fromEntity(option.entity).getSchema();
+                if (option.nullable) {
+                    scheme.nullable = true;
+                }
+                if (option.list) {
+                    this.data.properties[option.key] = {
+                        type: 'array',
+                        items: scheme,
+                    };
+                }
+                else {
+                    this.data.properties[option.key] = scheme;
+                }
+            }
+            if (option.required) {
+                this.data.required = [...(this.data.required || []), option.key];
+            }
+        }
+        return this;
+    }
+    getSchema() {
+        return this.data;
+    }
+    getSKeySchema() {
+        return {
+            [this.name]: this.data,
+        };
+    }
+    static fromEntity(e) {
+        const meta = getEntityMeta(e);
+        if (meta) {
+            return new ESchemaEditor(e, meta.name);
+        }
+        throw new Error('Entity metadata not found');
+    }
+    /**
+     * Generates a JSON schema representation from a CoreEntity instance.
+     *
+     * This method inspects the entity's metadata to construct a schema object
+     * describing the entity's shape. The resulting schema contains:
+     * - `type`: always `"object"`.
+     * - `description`: a string indicating the entity name.
+     * - `required`: an array of property names that are defined on the entity.
+     * - `properties`: an object mapping each property name to an object that
+     *   includes the resolved database type and its nullability.
+     *
+     * If no metadata is found for the provided entity, the method returns `undefined`.
+     *
+     * @param {T} entity - The entity instance for which to create a schema.
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
+     *          if the entity's metadata could not be retrieved.
+     */
+    static schemaFromEntity(entity) {
+        const schema = {
+            type: 'object',
+            properties: {},
+        };
+        const meta = getEntityMeta(entity);
+        if (!meta) {
+            return undefined;
+        }
+        schema.description = `Entity: ${meta.name}`;
+        schema.required = [];
+        const keys = Object.keys(entity);
+        keys.forEach((k) => {
+            const cMeta = getColumnMeta(entity, k);
+            if (cMeta && schema.properties) {
+                schema.required.push(k);
+                schema.properties[k] = {
+                    type: resolveDBType(cMeta.dataType),
+                    nullable: cMeta.canBeNull,
+                };
+            }
+        });
+        return schema;
+    }
+}

package/dist/mjs/Swagger/Path/SPathUtil.d.ts

@@ -1,16 +1,107 @@
 import { CoreEntity } from '@grandlinex/core';
 import { HttpStatusTypes } from '../Meta/SwaggerTypesStatic.js';
-import { SKey, SSchemaEl, SwaggerContent, SwaggerRPathConfResponse, SwaggerRPathReqBody } from '../Meta/SwaggerTypes.js';
+import { SKey, SSchemaEl, SSchemaElObj, SwaggerContent, SwaggerRPathConfResponse, SwaggerRPathReqBody } from '../Meta/SwaggerTypes.js';
+import { ESchemaEditor } from './ESchemaEditor.js';
 export default class SPathUtil {
+    /**
+     * Generates a default response mapping for the specified HTTP status types.
+     *
+     * @param {HttpStatusTypes[]} types - The HTTP status types for which default responses should be created.
+     * @return {SwaggerRPathConfResponse} An object mapping each provided status type to its default response definition. */
     static defaultResponse(...types: HttpStatusTypes[]): SwaggerRPathConfResponse;
+    /**
+     * Creates a request body definition for JSON content type using the provided schema.
+     *
+     * @param {SSchemaEl} schema - The JSON schema used for validating the request body.
+     * @return {SwaggerRPathReqBody} A Swagger path request body object specifying application/json content type with the provided schema.
+     */
     static jsonBody(schema: SSchemaEl): SwaggerRPathReqBody;
+    /**
+     * Builds a Swagger request body for `multipart/form-data` requests.
+     *
+     * @param {SSchemaEl} [schema] Optional schema describing the form data.
+     *        If omitted, a default schema with a single binary `file` field is provided.
+     * @return {SwaggerRPathReqBody} Swagger request body definition with
+     *         `multipart/form-data` content and the supplied or default schema. */
     static formBody(schema?: SSchemaEl): SwaggerRPathReqBody;
+    /**
+     * Generates a Swagger content definition for the provided entity.
+     *
+     * @param {T} entity - The entity instance to derive the Swagger schema from.
+     * @param {boolean} [list] - When true, the schema will be wrapped in an array type, representing a list of entities.
+     *
+     * @returns {SwaggerContent|undefined} The Swagger content object for the entity, or `undefined` if the entity does not have a schema.
+     */
     static entityContent<T extends CoreEntity>(entity: T, list?: boolean): SwaggerContent | undefined;
+    /**
+     * @template T extends CoreEntity
+     * @param {T} entity - The entity instance for which to build the response configuration.
+     * @param {boolean} [list] - Indicates whether the response should represent a list of entities.
+     * @param {boolean} [create] - Indicates whether the response corresponds to a creation operation (status code 201); otherwise 200.
+     * @returns {SwaggerRPathConfResponse} The Swagger response configuration object containing the appropriate status code and content.
+     */
     static entityResponse<T extends CoreEntity>(entity: T, list?: boolean, create?: boolean): SwaggerRPathConfResponse;
+    /**
+     * Builds a JSON schema reference path for the given component name.
+     *
+     * @param {string} inp - The name of the schema component.
+     * @return {string} The JSON reference path formatted as `#/components/schemas/<inp>`.
+     */
     static schemaPath(inp: string): string;
+    /**
+     * Creates a Swagger request body definition that references a schema.
+     *
+     * @param {string | CoreEntity} $ref
+     *   Either the string reference to a schema or a `CoreEntity` instance whose
+     *   class name will be used to build the reference path.
+     * @param {boolean} list
+     *   If true, the referenced schema is wrapped in an array; otherwise the
+     *   schema is used directly.
+     * @returns {SwaggerRPathReqBody}
+     *   The request body object containing the appropriate content and schema
+     *   configuration.
+     */
+    static refRequest($ref: string | CoreEntity, list: boolean): SwaggerRPathReqBody;
+    /**
+     * Creates a Swagger response configuration for a given HTTP status code.
+     *
+     * @param {HttpStatusTypes} code - The primary HTTP status code for */
     static refResponse(code: HttpStatusTypes, $ref: string | CoreEntity, list: boolean, ...addCodes: HttpStatusTypes[]): SwaggerRPathConfResponse;
+    /**
+     * Builds a Swagger response configuration object for a given HTTP status code and schema.
+     *
+     * @param {HttpStatusTypes} code - The primary HTTP status code for the response.
+     * @param {SSchemaEl} schema - The JSON schema definition for the response body.
+     * @param {boolean} list - If true, the schema is wrapped in an array for list responses.
+     * @param {...HttpStatusTypes} addCodes - Additional HTTP status codes for default responses.
+     * @return {SwaggerRPathConfResponse} The constructed response configuration object.
+     */
     static jsonResponse(code: HttpStatusTypes, schema: SSchemaEl, list: boolean, ...addCodes: HttpStatusTypes[]): SwaggerRPathConfResponse;
-    static schemaFromEntity<T extends CoreEntity>(entity: T): SSchemaEl | undefined;
+    /**
+     * Generates a JSON schema representation from a CoreEntity instance.
+     *
+     * This method inspects the entity's metadata to construct a schema object
+     * describing the entity's shape. The resulting schema contains:
+     * - `type`: always `"object"`.
+     * - `description`: a string indicating the entity name.
+     * - `required`: an array of property names that are defined on the entity.
+     * - `properties`: an object mapping each property name to an object that
+     *   includes the resolved database type and its nullability.
+     *
+     * If no metadata is found for the provided entity, the method returns `undefined`.
+     *
+     * @param {T} entity - The entity instance for which to create a schema.
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
+     *          if the entity's metadata could not be retrieved.
+     * @deprecated Use {@link ESchemaEditor.schemaFromEntity} instead.
+     */
+    static schemaFromEntity<T extends CoreEntity>(entity: T): SSchemaElObj | undefined;
+    /**
+     * Generates a content schema object for the given entity. The schema contains a description derived from the entity metadata and a JSON content schema based on the entity's structure.
+     *
+     * @param {T} entity - The entity instance for which to generate the content schema. The generic type `T` must extend {@link CoreEntity}.
+     * @returns {{ description: string; content: { 'application/json': { schema: SSchemaEl } }; } | undefined} An object containing the content schema, or `undefined` if no metadata is available for the entity.
+     */
     static contentSchemaFromEntity<T extends CoreEntity>(entity: T): {
         description: string;
         content: {
@@ -20,9 +111,20 @@ export default class SPathUtil {
         };
     } | undefined;
     /**
-     * generate global schema
-     * @param e
+     * Generates a mapping from entity names to their corresponding schema objects.
+     *
+     * @param {CoreEntity[]} e The entities for which schema entries should be generated.
+     * @return {SKey<SSchemaEl>} An object whose keys are entity names and values are the schemas derived from those entities.
+     */
+    static schemaEntryGen(...e: CoreEntity[]): SKey<SSchemaElObj>;
+    /**
+     * Builds a JSON schema representation for an entity view that includes both the
+     * entity data and its related entity map.
+     *
+     * @param entity The primary entity used to construct the `dat` portion of the schema.
+     * @param entityMap The related entity map used to construct the `join_map` portion of the schema.
+     * @returns A {@link SSchemaEl} object schema with properties `i`, `dat`, and `join_map`.
      */
-    static schemaEntryGen(...e: CoreEntity[]): SKey<SSchemaEl>;
     static schemaFromEntityView<A extends CoreEntity, B extends CoreEntity>(entity: A, entityMap: B): SSchemaEl;
+    static editor<J extends CoreEntity>(e: J): ESchemaEditor<J>;
 }

package/dist/mjs/Swagger/Path/SPathUtil.js

@@ -1,30 +1,12 @@
-import { getEntityMeta, XUtil, getColumnMeta, } from '@grandlinex/core';
+import { getEntityMeta, XUtil } from '@grandlinex/core';
 import map from './SUtilMap.js';
-function resolveDBType(dType) {
-    switch (dType) {
-        case 'int':
-        case 'long':
-            return 'integer';
-        case 'double':
-        case 'float':
-            return 'number';
-        case 'blob':
-            return 'string';
-        case 'string':
-        case 'text':
-        case 'uuid':
-            return 'string';
-        case 'boolean':
-            return 'boolean';
-        case 'date':
-            return 'string';
-        case 'json':
-            return 'object';
-        default:
-            throw Error('TypeNotSupported');
-    }
-}
+import { ESchemaEditor } from './ESchemaEditor.js';
 export default class SPathUtil {
+    /**
+     * Generates a default response mapping for the specified HTTP status types.
+     *
+     * @param {HttpStatusTypes[]} types - The HTTP status types for which default responses should be created.
+     * @return {SwaggerRPathConfResponse} An object mapping each provided status type to its default response definition. */
     static defaultResponse(...types) {
         const res = {};
         types.forEach((el) => {
@@ -32,6 +14,12 @@ export default class SPathUtil {
         });
         return res;
     }
+    /**
+     * Creates a request body definition for JSON content type using the provided schema.
+     *
+     * @param {SSchemaEl} schema - The JSON schema used for validating the request body.
+     * @return {SwaggerRPathReqBody} A Swagger path request body object specifying application/json content type with the provided schema.
+     */
     static jsonBody(schema) {
         return {
             content: {
@@ -41,6 +29,13 @@ export default class SPathUtil {
             },
         };
     }
+    /**
+     * Builds a Swagger request body for `multipart/form-data` requests.
+     *
+     * @param {SSchemaEl} [schema] Optional schema describing the form data.
+     *        If omitted, a default schema with a single binary `file` field is provided.
+     * @return {SwaggerRPathReqBody} Swagger request body definition with
+     *         `multipart/form-data` content and the supplied or default schema. */
     static formBody(schema) {
         return {
             content: {
@@ -59,6 +54,14 @@ export default class SPathUtil {
             },
         };
     }
+    /**
+     * Generates a Swagger content definition for the provided entity.
+     *
+     * @param {T} entity - The entity instance to derive the Swagger schema from.
+     * @param {boolean} [list] - When true, the schema will be wrapped in an array type, representing a list of entities.
+     *
+     * @returns {SwaggerContent|undefined} The Swagger content object for the entity, or `undefined` if the entity does not have a schema.
+     */
     static entityContent(entity, list) {
         const schema = this.schemaFromEntity(entity);
         if (!schema) {
@@ -80,6 +83,13 @@ export default class SPathUtil {
             },
         };
     }
+    /**
+     * @template T extends CoreEntity
+     * @param {T} entity - The entity instance for which to build the response configuration.
+     * @param {boolean} [list] - Indicates whether the response should represent a list of entities.
+     * @param {boolean} [create] - Indicates whether the response corresponds to a creation operation (status code 201); otherwise 200.
+     * @returns {SwaggerRPathConfResponse} The Swagger response configuration object containing the appropriate status code and content.
+     */
     static entityResponse(entity, list, create) {
         const code = create ? '201' : '200';
         const an = {};
@@ -89,9 +99,58 @@ export default class SPathUtil {
         };
         return an;
     }
+    /**
+     * Builds a JSON schema reference path for the given component name.
+     *
+     * @param {string} inp - The name of the schema component.
+     * @return {string} The JSON reference path formatted as `#/components/schemas/<inp>`.
+     */
     static schemaPath(inp) {
         return `#/components/schemas/${inp}`;
     }
+    /**
+     * Creates a Swagger request body definition that references a schema.
+     *
+     * @param {string | CoreEntity} $ref
+     *   Either the string reference to a schema or a `CoreEntity` instance whose
+     *   class name will be used to build the reference path.
+     * @param {boolean} list
+     *   If true, the referenced schema is wrapped in an array; otherwise the
+     *   schema is used directly.
+     * @returns {SwaggerRPathReqBody}
+     *   The request body object containing the appropriate content and schema
+     *   configuration.
+     */
+    static refRequest($ref, list) {
+        const t = typeof $ref === 'string'
+            ? { $ref }
+            : {
+                $ref: this.schemaPath(XUtil.getEntityNames($ref).className),
+            };
+        if (list) {
+            return {
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'array',
+                            items: t,
+                        },
+                    },
+                },
+            };
+        }
+        return {
+            content: {
+                'application/json': {
+                    schema: t,
+                },
+            },
+        };
+    }
+    /**
+     * Creates a Swagger response configuration for a given HTTP status code.
+     *
+     * @param {HttpStatusTypes} code - The primary HTTP status code for */
     static refResponse(code, $ref, list, ...addCodes) {
         const an = {
             ...this.defaultResponse(...addCodes),
@@ -126,6 +185,15 @@ export default class SPathUtil {
         }
         return an;
     }
+    /**
+     * Builds a Swagger response configuration object for a given HTTP status code and schema.
+     *
+     * @param {HttpStatusTypes} code - The primary HTTP status code for the response.
+     * @param {SSchemaEl} schema - The JSON schema definition for the response body.
+     * @param {boolean} list - If true, the schema is wrapped in an array for list responses.
+     * @param {...HttpStatusTypes} addCodes - Additional HTTP status codes for default responses.
+     * @return {SwaggerRPathConfResponse} The constructed response configuration object.
+     */
     static jsonResponse(code, schema, list, ...addCodes) {
         const an = {
             ...this.defaultResponse(...addCodes),
@@ -155,30 +223,33 @@ export default class SPathUtil {
         }
         return an;
     }
+    /**
+     * Generates a JSON schema representation from a CoreEntity instance.
+     *
+     * This method inspects the entity's metadata to construct a schema object
+     * describing the entity's shape. The resulting schema contains:
+     * - `type`: always `"object"`.
+     * - `description`: a string indicating the entity name.
+     * - `required`: an array of property names that are defined on the entity.
+     * - `properties`: an object mapping each property name to an object that
+     *   includes the resolved database type and its nullability.
+     *
+     * If no metadata is found for the provided entity, the method returns `undefined`.
+     *
+     * @param {T} entity - The entity instance for which to create a schema.
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
+     *          if the entity's metadata could not be retrieved.
+     * @deprecated Use {@link ESchemaEditor.schemaFromEntity} instead.
+     */
     static schemaFromEntity(entity) {
-        const schema = {
-            type: 'object',
-            properties: {},
-        };
-        const meta = getEntityMeta(entity);
-        if (!meta) {
-            return undefined;
-        }
-        schema.description = `Entity: ${meta.name}`;
-        schema.required = [];
-        const keys = Object.keys(entity);
-        keys.forEach((k) => {
-            const cMeta = getColumnMeta(entity, k);
-            if (cMeta && schema.properties) {
-                schema.required.push(k);
-                schema.properties[k] = {
-                    type: resolveDBType(cMeta.dataType),
-                    nullable: cMeta.canBeNull,
-                };
-            }
-        });
-        return schema;
+        return ESchemaEditor.schemaFromEntity(entity);
     }
+    /**
+     * Generates a content schema object for the given entity. The schema contains a description derived from the entity metadata and a JSON content schema based on the entity's structure.
+     *
+     * @param {T} entity - The entity instance for which to generate the content schema. The generic type `T` must extend {@link CoreEntity}.
+     * @returns {{ description: string; content: { 'application/json': { schema: SSchemaEl } }; } | undefined} An object containing the content schema, or `undefined` if no metadata is available for the entity.
+     */
     static contentSchemaFromEntity(entity) {
         const meta = getEntityMeta(entity);
         if (!meta) {
@@ -188,25 +259,35 @@ export default class SPathUtil {
             description: `Entity: ${meta.name}`,
             content: {
                 'application/json': {
-                    schema: this.schemaFromEntity(entity),
+                    schema: ESchemaEditor.schemaFromEntity(entity),
                 },
             },
         };
     }
     /**
-     * generate global schema
-     * @param e
+     * Generates a mapping from entity names to their corresponding schema objects.
+     *
+     * @param {CoreEntity[]} e The entities for which schema entries should be generated.
+     * @return {SKey<SSchemaEl>} An object whose keys are entity names and values are the schemas derived from those entities.
      */
     static schemaEntryGen(...e) {
         const out = {};
         e.forEach((el) => {
             const meta = getEntityMeta(el);
             if (meta) {
-                out[meta.name] = SPathUtil.schemaFromEntity(el);
+                out[meta.name] = ESchemaEditor.schemaFromEntity(el);
             }
         });
         return out;
     }
+    /**
+     * Builds a JSON schema representation for an entity view that includes both the
+     * entity data and its related entity map.
+     *
+     * @param entity The primary entity used to construct the `dat` portion of the schema.
+     * @param entityMap The related entity map used to construct the `join_map` portion of the schema.
+     * @returns A {@link SSchemaEl} object schema with properties `i`, `dat`, and `join_map`.
+     */
     static schemaFromEntityView(entity, entityMap) {
         return {
             type: 'object',
@@ -214,9 +295,12 @@ export default class SPathUtil {
                 i: {
                     type: 'integer',
                 },
-                dat: this.schemaFromEntity(entity),
-                join_map: this.schemaFromEntity(entityMap),
+                dat: ESchemaEditor.schemaFromEntity(entity),
+                join_map: ESchemaEditor.schemaFromEntity(entityMap),
             },
         };
     }
+    static editor(e) {
+        return ESchemaEditor.fromEntity(e);
+    }
 }

package/dist/mjs/Swagger/SwaggerUtil.d.ts

@@ -1,11 +1,27 @@
-import { ObjectLike } from '@grandlinex/core';
+import { CoreLogChannel, ObjectLike } from '@grandlinex/core';
 import { Server } from 'net';
 import { MergeInputType, SwaggerConfig, SwaggerRPath } from './Meta/SwaggerTypes.js';
 import { RouteData } from './annotation/index.js';
 export default class SwaggerUtil {
+    static logger: CoreLogChannel | null;
+    static getLogger(): CoreLogChannel;
     static writeMeta(conf: SwaggerConfig, kind: 'JSON' | 'YAML', path?: string): void;
     static readMeta(path: string): any;
-    static serveMeta(conf: SwaggerConfig, port?: number, auth?: string): Promise<Server | null>;
+    /**
+     * Serves a meta page for Swagger UI or rapi-doc.
+     *
+     * @param {SwaggerConfig} conf The swagger configuration to expose via `/spec`.
+     * @param {Object} [option] Options for serving the meta page.
+     * @param {'swagger-ui'|'rapi-doc'} [option.type='swagger-ui'] The type of UI to serve.
+     * @param {number} [option.port] The port to listen on. Defaults to 9000.
+     * @param {string} [option.auth] Optional authentication key appended to the URL.
+     * @returns {Promise<Server|null>} A promise that resolves with the created server instance or null.
+     */
+    static serveMeta(conf: SwaggerConfig, option?: {
+        type?: 'swagger-ui' | 'rapi-doc';
+        port?: number;
+        auth?: string;
+    }): Promise<Server | null>;
     static metaExtractor(root: ObjectLike, npmPackageVersion: boolean, ...path: ObjectLike[]): SwaggerConfig | undefined;
     static routeToSwaggerPath(route: RouteData): SwaggerRPath;
     static merge(root: SwaggerConfig, data: MergeInputType[]): SwaggerConfig;

package/dist/mjs/Swagger/SwaggerUtil.js

@@ -1,7 +1,7 @@
 import * as Path from 'path';
 import * as fs from 'fs';
 import jsyaml from 'js-yaml';
-import { CMap, instanceOfEntity } from '@grandlinex/core';
+import { CMap, CoreLogChannel, DefaultLogger, instanceOfEntity, } from '@grandlinex/core';
 import express from 'express';
 import * as process from 'process';
 import { getSComponent, getSPath, getSwaggerMeta } from './Meta/Swagger.js';
@@ -9,6 +9,13 @@ import PathHelp, { getBaseFolder } from '../PathHelp.js';
 import { getRouteMeta } from './annotation/index.js';
 import { SPathUtil } from '../index.js';
 export default class SwaggerUtil {
+    static getLogger() {
+        if (!this.logger) {
+            const logger = new DefaultLogger();
+            this.logger = new CoreLogChannel('SwaggerUtil', logger);
+        }
+        return this.logger;
+    }
     static writeMeta(conf, kind, path) {
         if (kind === 'JSON') {
             const p = Path.join(path || process.cwd(), 'openapi.json');
@@ -25,11 +32,25 @@ export default class SwaggerUtil {
             return JSON.parse(file);
         }
         catch (e) {
+            this.getLogger().error(e);
             return null;
         }
     }
-    static async serveMeta(conf, port, auth) {
-        const resFiles = PathHelp(getBaseFolder(), '..', 'res', 'html');
+    /**
+     * Serves a meta page for Swagger UI or rapi-doc.
+     *
+     * @param {SwaggerConfig} conf The swagger configuration to expose via `/spec`.
+     * @param {Object} [option] Options for serving the meta page.
+     * @param {'swagger-ui'|'rapi-doc'} [option.type='swagger-ui'] The type of UI to serve.
+     * @param {number} [option.port] The port to listen on. Defaults to 9000.
+     * @param {string} [option.auth] Optional authentication key appended to the URL.
+     * @returns {Promise<Server|null>} A promise that resolves with the created server instance or null.
+     */
+    static async serveMeta(conf, option) {
+        const type = option?.type ?? 'swagger-ui';
+        const port = option?.port || 9000;
+        const auth = option?.auth;
+        const resFiles = PathHelp(getBaseFolder(), '..', 'res', 'html', type);
         const key = auth ? `?auth=${auth}` : '';
         const app = express();
         app.use('/', express.static(resFiles));
@@ -37,8 +58,8 @@ export default class SwaggerUtil {
             res.status(200).send(conf);
         });
         return new Promise((resolve) => {
-            const s = app.listen(port || 9000, () => {
-                console.log(`listen on http://localhost:${port || 9000}${key}#`);
+            const s = app.listen(port, () => {
+                this.getLogger().log(`${type} listen on http://localhost:${port}${key}#`);
                 resolve(s);
             });
         });
@@ -83,7 +104,13 @@ export default class SwaggerUtil {
             // Handle requestBody
             if (!conf.requestBody) {
                 if (route.meta.requestSchema) {
-                    conf.requestBody = SPathUtil.jsonBody(route.meta.requestSchema);
+                    if (typeof route.meta.requestSchema === 'string' ||
+                        instanceOfEntity(route.meta.requestSchema)) {
+                        conf.requestBody = SPathUtil.refRequest(route.meta.requestSchema, route.meta.responseType === 'LIST');
+                    }
+                    else {
+                        conf.requestBody = SPathUtil.jsonBody(route.meta.requestSchema);
+                    }
                 }
             }
             // Handle responses