starlight-server 0.0.1 → 1.0.0

package/dist/demo/index.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { getFileDir } from '@anjianshi/utils/env-node/index.js';
 import { getLogger, startHTTPServer, DefaultRouter } from '../index.js';
-// import { registerSwaggerRoute } from '../swagger/index.js'
+import { registerSwaggerRoute } from '../swagger/index.js';
 const logger = getLogger({
     level: 'debug',
     debugLib: '*',
@@ -12,14 +12,31 @@ const logger = getLogger({
 const router = new DefaultRouter();
 router.registerResponseReference('hello', { object: [{ name: 'hello', type: 'string' }] });
 router.register({
+    category: 'demo',
+    description: 'hello world',
     method: 'GET',
     path: '/hello',
-    response: { ref: 'hello' },
+    body: [
+        { name: 'abc', type: 'number' },
+        { name: 'def', type: { array: { type: 'string' } } },
+    ],
+    response: {
+        object: [{ name: 'key', type: 'string' }],
+    },
     handler({ response }) {
         response.json({ hello: 'world' });
     },
 });
-// registerSwaggerRoute(router)
+router.register({
+    category: 'demo',
+    method: 'POST',
+    path: '/hello',
+    response: { ref: 'hello' },
+    handler({ response }) {
+        response.json({ hello: 'world post' });
+    },
+});
+registerSwaggerRoute(router);
 startHTTPServer({
     handler: router.handle,
     logger: logger.getChild('http'),

package/dist/router/index.d.ts

@@ -35,4 +35,4 @@
  */
 export * from './router.js';
 export { type PathParameters } from './match.js';
-export type { BasicDataType, Parameter, ParameterDataType } from './parameters.js';
+export type { BasicDataType, Parameter, BasicParameter, ParameterDataType } from './parameters.js';

package/dist/router/parameters.d.ts

@@ -12,7 +12,7 @@ export interface Parameter {
     /** 字段名 */
     name: string;
     /** 文字描述  */
-    describe?: string;
+    description?: string;
     type: ParameterDataType;
     /** 默认值，应与 type 匹配。若指定，则不再需要 required 规则。 */
     defaults?: unknown;
@@ -24,7 +24,7 @@ export interface Parameter {
     validate?: Record<string, unknown>;
 }
 export type BasicDataType = 'string' | 'number' | 'boolean';
-type BasicParameter = Pick<Parameter, 'type' | 'validate' | 'required' | 'nullable' | 'defaults'>;
+export type BasicParameter = Pick<Parameter, 'type' | 'validate' | 'required' | 'nullable' | 'defaults' | 'description'>;
 /**
  * 请求参数的数据类型定义
  */
@@ -48,4 +48,3 @@ export declare function parseQuery<T>(route: Route, request: Request): T;
  * 验证 body 内容
  */
 export declare function parseJSONBody<T>(route: Route, request: Request): Promise<T>;
-export {};

package/dist/router/router.d.ts

@@ -28,12 +28,12 @@ export type RouteHandler<Ctx extends BaseContext = BaseContext, PathP extends Pa
  * - 有默认值的字段均填充了默认值
  * - method 一定为全大写
  */
-export type Route<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> = RequiredFields<RawRoute<Ctx, PathP>, 'describe' | 'category' | 'method'>;
+export type Route<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> = RequiredFields<RawRoute<Ctx, PathP>, 'description' | 'category' | 'method'>;
 export interface RawRoute<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> {
     /** 接口路径。支持变量（/abc/:xxx/def），详见 src/router/match.ts */
     path: string;
     /** 接口描述  */
-    describe?: string;
+    description?: string;
     /** 接口类别 */
     category?: string;
     /** 接口 HTTP Method，有 body 定义的默认为 POST，否则默认为 GET */
@@ -74,7 +74,7 @@ export interface ResponseObjectItemType {
     /** 字段名 */
     name: string;
     /** 文字描述  */
-    describe?: string;
+    description?: string;
     /** 值类型。ResponseDataType[] 代表有多种可能的类型 */
     type: ResponseDataType | ResponseDataType[];
 }

package/dist/router/router.js

@@ -15,7 +15,7 @@ export class Router {
     register(raw, path, handler) {
         const rawRoute = typeof raw === 'string' ? { method: raw, path: path, handler: handler } : raw;
         const route = {
-            describe: '',
+            description: '',
             category: '',
             ...rawRoute,
             method: (rawRoute.method ?? (rawRoute.body ? 'POST' : 'GET')).toUpperCase(),

package/dist/swagger/factory.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 把路由定义转换成 swagger API 定义的工具函数
+ */
+import type { Route, ResponseDataType, BasicParameter } from '../router/index.js';
+import type { Schema, Reference, PathItem } from './openapi-spec.js';
+type AnyObject = {
+    [k: string]: unknown;
+};
+/**
+ * 基本数据类型
+ */
+export declare function string(description?: string, options?: AnyObject): {
+    type: string;
+    description: string | undefined;
+};
+export declare function number(description?: string, options?: AnyObject): {
+    type: string;
+    description: string | undefined;
+};
+export declare function boolean(description?: string, options?: AnyObject): {
+    type: string;
+    description: string | undefined;
+};
+export declare function object(properties: Record<string, Schema>, extra?: AnyObject): {
+    type: "object";
+    properties: Record<string, Schema>;
+};
+export declare function array(items: Schema, extra?: AnyObject): {
+    type: "array";
+    items: Schema;
+};
+/**
+ * 对 components/schemas 中定义的数据类型的引用
+ */
+export declare function ref(name: string, summary?: string, description?: string): Reference;
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于响应内容）
+ */
+export declare function responseSchema(type: ResponseDataType | ResponseDataType[]): Schema | Reference;
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于请求内容）
+ */
+export declare function parameterSchema(parameter: BasicParameter): Schema;
+/**
+ * 生成 JSON 形式的 content
+ */
+export declare function jsonMedia(schema: string | Schema): {
+    content: {
+        'application/json': {
+            schema: Schema | Reference;
+        };
+    };
+};
+/**
+ * 把一系列路由转换成 swagger API 定义
+ */
+export declare function paths(routes: Route[]): Record<string, PathItem>;
+/**
+ * 单个路由定义
+ */
+export declare function operation(route: Route): {
+    tags: string[];
+    summary: string;
+    operationId: string;
+    requestBody: {
+        content: {
+            'application/json': {
+                schema: Schema | Reference;
+            };
+        };
+    } | undefined;
+    responses: {
+        default: {
+            content: {
+                'application/json': {
+                    schema: Schema | Reference;
+                };
+            };
+            description: string;
+        };
+    };
+};
+/**
+ * 生成路由的唯一 ID
+ */
+export declare function operationId(route: Route): string;
+/**
+ * 路由请求参数转为 swagger 定义
+ */
+export declare function requestBody(route: Route): {
+    content: {
+        'application/json': {
+            schema: Schema | Reference;
+        };
+    };
+} | undefined;
+export {};

package/dist/swagger/factory.js

@@ -0,0 +1,144 @@
+/**
+ * 基本数据类型
+ */
+export function string(description, options) {
+    return { type: 'string', description, ...(options ?? {}) };
+}
+export function number(description, options) {
+    return { type: 'number', description, ...(options ?? {}) };
+}
+export function boolean(description, options) {
+    return { type: 'boolean', description, ...(options ?? {}) };
+}
+export function object(properties, extra) {
+    return { type: 'object', properties, ...(extra ?? {}) };
+}
+export function array(items, extra) {
+    return { type: 'array', items, ...(extra ?? {}) };
+}
+/**
+ * 对 components/schemas 中定义的数据类型的引用
+ */
+export function ref(name, summary, description) {
+    return { $ref: '#/components/schemas/' + name, summary, description };
+}
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于响应内容）
+ */
+export function responseSchema(type) {
+    if (Array.isArray(type)) {
+        return {
+            oneOf: type
+                .filter((subType) => subType !== 'null')
+                .map(responseSchema),
+            nullable: type.includes('null'),
+        };
+    }
+    if (typeof type === 'string')
+        return { type };
+    if ('ref' in type)
+        return ref(type.ref, type.summary, type.description);
+    if ('array' in type)
+        return array(responseSchema(type.array));
+    if ('object' in type) {
+        return object(type.object.reduce((properties, property) => ({
+            ...properties,
+            [property.name]: { ...responseSchema(property.type), description: property.description },
+        }), {}));
+    }
+    return {};
+}
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于请求内容）
+ */
+export function parameterSchema(parameter) {
+    const schema = {
+        description: parameter.description,
+        nullable: parameter.nullable,
+        default: parameter.defaults,
+    };
+    if (typeof parameter.type === 'string') {
+        schema.type = parameter.type;
+    }
+    else if ('array' in parameter.type) {
+        const arraySchema = array(parameterSchema(parameter.type.array));
+        Object.assign(schema, arraySchema);
+    }
+    else if ('record' in parameter.type) {
+        const innerSchema = parameterSchema(parameter.type.record);
+        Object.assign(schema, object({}, { additionalProperties: innerSchema }));
+    }
+    else if ('object' in parameter.type) {
+        const objectSchema = object(Object.entries(parameter.type.object).reduce((properties, [name, subParameter]) => ({
+            ...properties,
+            [name]: parameterSchema(subParameter),
+        }), {}));
+        Object.assign(schema, objectSchema);
+    }
+    return schema;
+}
+/**
+ * 生成 JSON 形式的 content
+ */
+export function jsonMedia(schema) {
+    return {
+        content: {
+            'application/json': {
+                schema: typeof schema === 'string' ? ref(schema) : schema,
+            },
+        },
+    };
+}
+/**
+ * 把一系列路由转换成 swagger API 定义
+ */
+export function paths(routes) {
+    const paths = {};
+    for (const route of routes) {
+        if (route.category === 'swagger')
+            continue;
+        if (!paths[route.path])
+            paths[route.path] = {};
+        const pathItem = paths[route.path];
+        const method = route.method.toLowerCase();
+        pathItem[method] = operation(route);
+    }
+    return paths;
+}
+/**
+ * 单个路由定义
+ */
+export function operation(route) {
+    return {
+        tags: route.category ? [route.category] : [],
+        summary: route.description,
+        operationId: operationId(route),
+        requestBody: requestBody(route),
+        responses: {
+            default: {
+                description: 'OK',
+                ...jsonMedia(route.response !== undefined ? responseSchema(route.response) : object({})),
+            },
+        },
+    };
+}
+/**
+ * 生成路由的唯一 ID
+ */
+export function operationId(route) {
+    return `${route.method}-${route.path}`;
+}
+/**
+ * 路由请求参数转为 swagger 定义
+ */
+export function requestBody(route) {
+    if (!route.body)
+        return;
+    return jsonMedia({
+        type: 'object',
+        properties: route.body.reduce((properties, parameter) => ({
+            ...properties,
+            [parameter.name]: parameterSchema(parameter),
+        }), {}),
+    });
+}

package/dist/swagger/index.d.ts

@@ -1 +1,8 @@
+import type { Router } from '../router/index.js';
+import type { OpenAPI } from './openapi-spec.js';
+export declare function registerSwaggerRoute(router: Router, endpoint?: string, customFields?: OpenAPICustomFields, swaggerOptions?: Record<string, unknown>): void;
+/**
+ * swagger API 路由
+ */
+type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>;
 export {};

package/dist/swagger/index.js

@@ -1,168 +1,67 @@
-// import fsPromise from 'node:fs/promises'
-// import path from 'node:path'
-// import { getAbsoluteFSPath } from 'swagger-ui-dist'
-// import { HTTPError } from '../http/index.js'
-// import {
-//   type Router,
-//   type PathParameters,
-//   type BaseContext,
-//   type ResponseDataType,
-// } from '../router/index.js'
-// import { normalizePath } from '../router/match.js'
-// import type { OpenAPI, Schema, PathItem } from './openapi-spec.js'
-export {};
-// export function registerSwaggerRoute(
-//   router: Router,
-//   endpoint: string = '/swagger',
-//   customFields: OpenAPICustomFields = { info: { title: 'API Document', version: '0.0.1' } },
-// ) {
-//   router.register('GET', normalizePath(endpoint) + '/*', pageRoute)
-//   router.register(
-//     'GET',
-//     normalizePath(endpoint) + '/api-swagger.json',
-//     apiRoute.bind(null, router, customFields),
-//   )
-// }
-// /**
-//  * ---------------------------------
-//  * swagger 页面路由
-//  * ---------------------------------
-//  */
-// async function pageRoute({ response }: BaseContext, pathParameters: PathParameters) {
-//   const file = (pathParameters['*'] ?? '') || 'index.html'
-//   const swaggerDir = getAbsoluteFSPath()
-//   const abspath = path.join(swaggerDir, file)
-//   if (!cache.has(abspath)) {
-//     try {
-//       const stat = await fsPromise.stat(abspath)
-//       if (!stat.isFile()) throw new HTTPError(404)
-//     } catch (e) {
-//       throw new HTTPError(404)
-//     }
-//     const content = await fsPromise.readFile(abspath)
-//     const replacemented = replacement(abspath, content)
-//     cache.set(abspath, replacemented)
-//   }
-//   response.text(cache.get(abspath)!)
-// }
-// const cache = new Map<string, Buffer | string>()
-// function replacement(abspath: string, content: Buffer) {
-//   if (/swagger-initializer.js/.exec(abspath)) {
-//     return content
-//       .toString()
-//       .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json')
-//     // .replace('SwaggerUIBundle({', 'SwaggerUIBundle({\n    defaultModelsExpandDepth: 1,\n    defaultModelExpandDepth: 1,')
-//   }
-//   return content
-// }
-// /**
-//  * ---------------------------------
-//  * swagger API 路由
-//  * ---------------------------------
-//  */
-// type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>
-// function apiRoute(router: Router, customFields: OpenAPICustomFields, { response }: BaseContext) {
-//   const swaggerJSON: OpenAPI = {
-//     ...customFields,
-//     openapi: '3.1.0',
-//     paths: makePaths(router),
-//     components: {
-//       schemas: makeRefs(router),
-//     },
-//   }
-//   response.json(swaggerJSON)
-// }
-// function makeRefs(router: Router) {
-//   const schemas: Record<string, Schema> = {}
-//   for (const [id, type] of Object.entries(router.responseReferences)) {
-//     schemas[id] = responseDataType2Schema(type)
-//   }
-//   return schemas
-// }
-// function makePaths(router: Router) {
-//   const paths: Record<string, PathItem> = {}
-//   return paths
-// }
-// function responseDataType2Schema(type: ResponseDataType): Schema {
-//   if (type === 'null') return { nullable: true }
-//   if (typeof type === 'object' && 'array' in type && type.array.includes('null')) {
-//     return {
-//       nullable: true,
-//       ...responseDataType2Schema(type as ResponseDataType.filter(v => v !== 'null') as ResponseDataType),
-//     }
-//   }
-//   const nullable = type === 'null' || (Array.isArray(type) && type.includes('null'))
-//   return {
-//     nullable,
-//   }
-// }
-// type Obj = { [k: string]: unknown }
-// function string(desc?: string, options?: Obj) {
-//   return { type: 'string', description: desc, ...(options ?? {}) }
-// }
-// function number(desc?: string, options?: Obj) {
-//   return { type: 'number', description: desc, ...(options ?? {}) }
-// }
-// function boolean(desc?: string, options?: Obj) {
-//   return { type: 'boolean', description: desc, ...(options ?? {}) }
-// }
-// function object(properties: unknown, extra?: Obj) {
-//   return { type: 'object', properties, ...(extra ?? {}) }
-// }
-// function array(items: unknown, extra?: Obj) {
-//   return { type: 'array', items, ...(extra ?? {}) }
-// }
-// function ref(name: string) {
-//   return { $ref: '#/components/schemas/' + name }
-// }
-// function jsonSchema(schema: string | Obj) {
-//   return {
-//     content: {
-//       'application/json': {
-//         schema: typeof schema === 'string' ? ref(schema) : schema,
-//       },
-//     },
-//   }
-// }
-// function route(params: {
-//   category: string
-//   describe: string
-//   path: string
-//   body?: string | Obj
-//   response?: string | Obj
-// }) {
-//   return {
-//     [params.path]: {
-//       post: {
-//         tags: [params.category],
-//         summary: params.describe,
-//         operationId: params.path,
-//         requestBody: params.body !== undefined ? jsonSchema(params.body) : undefined,
-//         responses: {
-//           default: {
-//             description: 'OK',
-//             ...jsonSchema(params.response ?? object({})),
-//           },
-//         },
-//       },
-//     },
-//   }
-// }
-// function response(schema: unknown) {
-//   return {
-//     type: 'object',
-//     properties: {
-//       success: boolean(undefined, { enum: [true] }),
-//       data: schema,
-//     },
-//   }
-// }
-// function pageResp(itemSchema: unknown) {
-//   return response({
-//     type: 'object',
-//     properties: {
-//       total: number(),
-//       list: array(itemSchema),
-//     },
-//   })
-// }
+import fsPromise from 'node:fs/promises';
+import path from 'node:path';
+import { getAbsoluteFSPath } from 'swagger-ui-dist';
+import { HTTPError } from '../http/index.js';
+import { normalizePath } from '../router/match.js';
+import * as factory from './factory.js';
+export function registerSwaggerRoute(router, endpoint = '/swagger', customFields = { info: { title: 'API Document', version: '0.0.1' } }, swaggerOptions) {
+    router.register({
+        category: 'swagger',
+        method: 'GET',
+        path: normalizePath(endpoint) + '/*',
+        handler: pageRoute.bind(null, swaggerOptions),
+    });
+    router.register({
+        category: 'swagger',
+        method: 'GET',
+        path: normalizePath(endpoint) + '/api-swagger.json',
+        handler: apiRoute.bind(null, router, customFields),
+    });
+}
+/**
+ * swagger 页面路由
+ */
+async function pageRoute(swaggerOptions, // Example: { defaultModelsExpandDepth: 1, defaultModelExpandDepth: 1 }
+{ response }, pathParameters) {
+    const file = (pathParameters['*'] ?? '') || 'index.html';
+    const swaggerDir = getAbsoluteFSPath();
+    const abspath = path.join(swaggerDir, file);
+    if (!cache.has(abspath)) {
+        try {
+            const stat = await fsPromise.stat(abspath);
+            if (!stat.isFile())
+                throw new HTTPError(404);
+        }
+        catch (e) {
+            throw new HTTPError(404);
+        }
+        const content = await fsPromise.readFile(abspath);
+        const replacemented = replacement(abspath, content, swaggerOptions);
+        cache.set(abspath, replacemented);
+    }
+    response.text(cache.get(abspath));
+}
+const cache = new Map();
+function replacement(abspath, content, swaggerOptions) {
+    if (/swagger-initializer.js/.exec(abspath)) {
+        let formatted = content
+            .toString()
+            .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json');
+        if (swaggerOptions) {
+            formatted = formatted.replace('SwaggerUIBundle({', 'SwaggerUIBundle({\n    ' + JSON.stringify(swaggerOptions).slice(1, -1) + ',\n');
+        }
+        return formatted;
+    }
+    return content;
+}
+function apiRoute(router, customFields, { response }) {
+    const swaggerJSON = {
+        ...customFields,
+        openapi: '3.1.0',
+        paths: factory.paths(router.routes),
+        components: {
+            schemas: Object.entries(router.responseReferences).reduce((schemas, [name, type]) => ({ ...schemas, [name]: factory.responseSchema(type) }), {}),
+        },
+    };
+    response.json(swaggerJSON);
+}

package/dist/swagger/openapi-spec.d.ts

@@ -126,7 +126,7 @@ export interface Responses extends Extendable {
     [HTTPStatus: string]: Response | Reference;
 }
 export interface Response extends Extendable {
-    descriptoin: CommonMark;
+    description: CommonMark;
     headers?: Record<string, Header | Reference>;
     content?: Record<string, MediaType>;
     links?: Record<string, Link | Reference>;
@@ -156,8 +156,8 @@ export interface Tag extends Extendable {
 }
 export interface Reference {
     $ref: string;
-    summary: string;
-    description: string;
+    summary?: string;
+    description?: string;
 }
 export interface Schema extends Extendable {
     nullable?: boolean;

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "starlight-server",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Simple But Powerful Node.js HTTP Server",
   "type": "module",
   "scripts": {
-    "watch": "rimraf dist && tsc && (concurrently \"tsc -w\" \"tsc-alias -w\")",
+    "dev": "npm run build && (concurrently \"tsc -w\" \"tsc-alias -w\" \"nodemon dist/demo/index.js\")",
     "build": "rimraf dist && tsc && tsc-alias",
-    "demo": "node dist/demo/index.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -45,6 +44,7 @@
     "@types/swagger-ui-dist": "^3.30.4",
     "concurrently": "^8.2.1",
     "eslint": "^8.54.0",
+    "nodemon": "^3.0.2",
     "rimraf": "^4.3.0",
     "tsc-alias": "^1.8.8",
     "typescript": "^5.3.2"

package/src/demo/index.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 import { getFileDir } from '@anjianshi/utils/env-node/index.js'
 import { getLogger, startHTTPServer, DefaultRouter } from '@/index.js'
-// import { registerSwaggerRoute } from '@/swagger/index.js'
+import { registerSwaggerRoute } from '@/swagger/index.js'
 
 const logger = getLogger({
   level: 'debug',
@@ -16,15 +16,33 @@ const router = new DefaultRouter()
 router.registerResponseReference('hello', { object: [{ name: 'hello', type: 'string' }] })
 
 router.register({
+  category: 'demo',
+  description: 'hello world',
   method: 'GET',
   path: '/hello',
-  response: { ref: 'hello' },
+  body: [
+    { name: 'abc', type: 'number' },
+    { name: 'def', type: { array: { type: 'string' } } },
+  ],
+  response: {
+    object: [{ name: 'key', type: 'string' }],
+  },
   handler({ response }) {
     response.json({ hello: 'world' })
   },
 })
 
-// registerSwaggerRoute(router)
+router.register({
+  category: 'demo',
+  method: 'POST',
+  path: '/hello',
+  response: { ref: 'hello' },
+  handler({ response }) {
+    response.json({ hello: 'world post' })
+  },
+})
+
+registerSwaggerRoute(router)
 
 startHTTPServer({
   handler: router.handle,

package/src/router/index.ts

@@ -35,4 +35,4 @@
  */
 export * from './router.js'
 export { type PathParameters } from './match.js'
-export type { BasicDataType, Parameter, ParameterDataType } from './parameters.js'
+export type { BasicDataType, Parameter, BasicParameter, ParameterDataType } from './parameters.js'

package/src/router/parameters.ts

@@ -21,7 +21,7 @@ export interface Parameter {
   name: string
 
   /** 文字描述  */
-  describe?: string
+  description?: string
 
   type: ParameterDataType
 
@@ -40,7 +40,10 @@ export interface Parameter {
 
 export type BasicDataType = 'string' | 'number' | 'boolean'
 
-type BasicParameter = Pick<Parameter, 'type' | 'validate' | 'required' | 'nullable' | 'defaults'>
+export type BasicParameter = Pick<
+  Parameter,
+  'type' | 'validate' | 'required' | 'nullable' | 'defaults' | 'description'
+>
 
 /**
  * 请求参数的数据类型定义

package/src/router/router.ts

@@ -38,7 +38,7 @@ export type RouteHandler<
 export type Route<
   Ctx extends BaseContext = BaseContext,
   PathP extends PathParameters = PathParameters,
-> = RequiredFields<RawRoute<Ctx, PathP>, 'describe' | 'category' | 'method'>
+> = RequiredFields<RawRoute<Ctx, PathP>, 'description' | 'category' | 'method'>
 
 export interface RawRoute<
   Ctx extends BaseContext = BaseContext,
@@ -48,7 +48,7 @@ export interface RawRoute<
   path: string
 
   /** 接口描述  */
-  describe?: string
+  description?: string
 
   /** 接口类别 */
   category?: string
@@ -96,7 +96,7 @@ export interface ResponseObjectItemType {
   name: string
 
   /** 文字描述  */
-  describe?: string
+  description?: string
 
   /** 值类型。ResponseDataType[] 代表有多种可能的类型 */
   type: ResponseDataType | ResponseDataType[]
@@ -131,7 +131,7 @@ export abstract class Router<Ctx extends BaseContext = BaseContext> {
     const rawRoute: RawRoute<Ctx, PathParameters & P> =
       typeof raw === 'string' ? { method: raw, path: path!, handler: handler! } : raw
     const route: Route<Ctx, PathParameters & P> = {
-      describe: '',
+      description: '',
       category: '',
       ...rawRoute,
       method: (rawRoute.method ?? (rawRoute.body ? 'POST' : 'GET')).toUpperCase(),

package/src/swagger/factory.ts

@@ -0,0 +1,169 @@
+/**
+ * 把路由定义转换成 swagger API 定义的工具函数
+ */
+import type { Route, ResponseDataType, BasicParameter } from '@/router/index.js'
+import type { Schema, Reference, PathItem } from './openapi-spec.js'
+
+type AnyObject = { [k: string]: unknown }
+
+/**
+ * 基本数据类型
+ */
+export function string(description?: string, options?: AnyObject) {
+  return { type: 'string', description, ...(options ?? {}) }
+}
+export function number(description?: string, options?: AnyObject) {
+  return { type: 'number', description, ...(options ?? {}) }
+}
+export function boolean(description?: string, options?: AnyObject) {
+  return { type: 'boolean', description, ...(options ?? {}) }
+}
+export function object(properties: Record<string, Schema>, extra?: AnyObject) {
+  return { type: 'object' as const, properties, ...(extra ?? {}) }
+}
+export function array(items: Schema, extra?: AnyObject) {
+  return { type: 'array' as const, items, ...(extra ?? {}) }
+}
+
+/**
+ * 对 components/schemas 中定义的数据类型的引用
+ */
+export function ref(name: string, summary?: string, description?: string): Reference {
+  return { $ref: '#/components/schemas/' + name, summary, description }
+}
+
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于响应内容）
+ */
+export function responseSchema(type: ResponseDataType | ResponseDataType[]): Schema | Reference {
+  if (Array.isArray(type)) {
+    return {
+      oneOf: type
+        .filter((subType): subType is Exclude<typeof subType, 'null'> => subType !== 'null')
+        .map(responseSchema),
+      nullable: type.includes('null'),
+    }
+  }
+
+  if (typeof type === 'string') return { type }
+  if ('ref' in type) return ref(type.ref, type.summary, type.description)
+  if ('array' in type) return array(responseSchema(type.array))
+  if ('object' in type) {
+    return object(
+      type.object.reduce(
+        (properties, property) => ({
+          ...properties,
+          [property.name]: { ...responseSchema(property.type), description: property.description },
+        }),
+        {},
+      ),
+    )
+  }
+
+  return {}
+}
+
+/**
+ * 可放置于 components/schemas 中的数据类型定义（用于请求内容）
+ */
+export function parameterSchema(parameter: BasicParameter): Schema {
+  const schema: Schema = {
+    description: parameter.description,
+    nullable: parameter.nullable,
+    default: parameter.defaults,
+  }
+  if (typeof parameter.type === 'string') {
+    schema.type = parameter.type
+  } else if ('array' in parameter.type) {
+    const arraySchema = array(parameterSchema(parameter.type.array))
+    Object.assign(schema, arraySchema)
+  } else if ('record' in parameter.type) {
+    const innerSchema = parameterSchema(parameter.type.record)
+    Object.assign(schema, object({}, { additionalProperties: innerSchema }))
+  } else if ('object' in parameter.type) {
+    const objectSchema = object(
+      Object.entries(parameter.type.object).reduce(
+        (properties, [name, subParameter]) => ({
+          ...properties,
+          [name]: parameterSchema(subParameter),
+        }),
+        {},
+      ),
+    )
+    Object.assign(schema, objectSchema)
+  }
+  return schema
+}
+
+/**
+ * 生成 JSON 形式的 content
+ */
+export function jsonMedia(schema: string | Schema) {
+  return {
+    content: {
+      'application/json': {
+        schema: typeof schema === 'string' ? ref(schema) : schema,
+      },
+    },
+  }
+}
+
+/**
+ * 把一系列路由转换成 swagger API 定义
+ */
+export function paths(routes: Route[]) {
+  const paths: Record<string, PathItem> = {}
+
+  for (const route of routes) {
+    if (route.category === 'swagger') continue
+
+    if (!paths[route.path]) paths[route.path] = {}
+    const pathItem = paths[route.path]!
+    const method = route.method.toLowerCase() as 'get'
+    pathItem[method] = operation(route)
+  }
+
+  return paths
+}
+
+/**
+ * 单个路由定义
+ */
+export function operation(route: Route) {
+  return {
+    tags: route.category ? [route.category] : [],
+    summary: route.description,
+    operationId: operationId(route),
+    requestBody: requestBody(route),
+    responses: {
+      default: {
+        description: 'OK',
+        ...jsonMedia(route.response !== undefined ? responseSchema(route.response) : object({})),
+      },
+    },
+  }
+}
+
+/**
+ * 生成路由的唯一 ID
+ */
+export function operationId(route: Route) {
+  return `${route.method}-${route.path}`
+}
+
+/**
+ * 路由请求参数转为 swagger 定义
+ */
+export function requestBody(route: Route) {
+  if (!route.body) return
+  return jsonMedia({
+    type: 'object',
+    properties: route.body.reduce(
+      (properties, parameter) => ({
+        ...properties,
+        [parameter.name]: parameterSchema(parameter),
+      }),
+      {},
+    ),
+  })
+}

package/src/swagger/index.ts

@@ -1,184 +1,92 @@
-// import fsPromise from 'node:fs/promises'
-// import path from 'node:path'
-// import { getAbsoluteFSPath } from 'swagger-ui-dist'
-// import { HTTPError } from '@/http/index.js'
-// import {
-//   type Router,
-//   type PathParameters,
-//   type BaseContext,
-//   type ResponseDataType,
-// } from '@/router/index.js'
-// import { normalizePath } from '@/router/match.js'
-// import type { OpenAPI, Schema, PathItem } from './openapi-spec.js'
-
-// export function registerSwaggerRoute(
-//   router: Router,
-//   endpoint: string = '/swagger',
-//   customFields: OpenAPICustomFields = { info: { title: 'API Document', version: '0.0.1' } },
-// ) {
-//   router.register('GET', normalizePath(endpoint) + '/*', pageRoute)
-//   router.register(
-//     'GET',
-//     normalizePath(endpoint) + '/api-swagger.json',
-//     apiRoute.bind(null, router, customFields),
-//   )
-// }
-
-// /**
-//  * ---------------------------------
-//  * swagger 页面路由
-//  * ---------------------------------
-//  */
-// async function pageRoute({ response }: BaseContext, pathParameters: PathParameters) {
-//   const file = (pathParameters['*'] ?? '') || 'index.html'
-
-//   const swaggerDir = getAbsoluteFSPath()
-//   const abspath = path.join(swaggerDir, file)
-//   if (!cache.has(abspath)) {
-//     try {
-//       const stat = await fsPromise.stat(abspath)
-//       if (!stat.isFile()) throw new HTTPError(404)
-//     } catch (e) {
-//       throw new HTTPError(404)
-//     }
-//     const content = await fsPromise.readFile(abspath)
-//     const replacemented = replacement(abspath, content)
-//     cache.set(abspath, replacemented)
-//   }
-//   response.text(cache.get(abspath)!)
-// }
-
-// const cache = new Map<string, Buffer | string>()
-
-// function replacement(abspath: string, content: Buffer) {
-//   if (/swagger-initializer.js/.exec(abspath)) {
-//     return content
-//       .toString()
-//       .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json')
-//     // .replace('SwaggerUIBundle({', 'SwaggerUIBundle({\n    defaultModelsExpandDepth: 1,\n    defaultModelExpandDepth: 1,')
-//   }
-//   return content
-// }
-
-// /**
-//  * ---------------------------------
-//  * swagger API 路由
-//  * ---------------------------------
-//  */
-// type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>
-
-// function apiRoute(router: Router, customFields: OpenAPICustomFields, { response }: BaseContext) {
-//   const swaggerJSON: OpenAPI = {
-//     ...customFields,
-//     openapi: '3.1.0',
-//     paths: makePaths(router),
-//     components: {
-//       schemas: makeRefs(router),
-//     },
-//   }
-//   response.json(swaggerJSON)
-// }
-
-// function makeRefs(router: Router) {
-//   const schemas: Record<string, Schema> = {}
-//   for (const [id, type] of Object.entries(router.responseReferences)) {
-//     schemas[id] = responseDataType2Schema(type)
-//   }
-//   return schemas
-// }
-
-// function makePaths(router: Router) {
-//   const paths: Record<string, PathItem> = {}
-//   return paths
-// }
-
-// function responseDataType2Schema(type: ResponseDataType): Schema {
-//   if (type === 'null') return { nullable: true }
-//   if (typeof type === 'object' && 'array' in type && type.array.includes('null')) {
-//     return {
-//       nullable: true,
-//       ...responseDataType2Schema(type as ResponseDataType.filter(v => v !== 'null') as ResponseDataType),
-//     }
-//   }
-
-//   const nullable = type === 'null' || (Array.isArray(type) && type.includes('null'))
-//   return {
-//     nullable,
-//   }
-// }
-
-// type Obj = { [k: string]: unknown }
-// function string(desc?: string, options?: Obj) {
-//   return { type: 'string', description: desc, ...(options ?? {}) }
-// }
-// function number(desc?: string, options?: Obj) {
-//   return { type: 'number', description: desc, ...(options ?? {}) }
-// }
-// function boolean(desc?: string, options?: Obj) {
-//   return { type: 'boolean', description: desc, ...(options ?? {}) }
-// }
-// function object(properties: unknown, extra?: Obj) {
-//   return { type: 'object', properties, ...(extra ?? {}) }
-// }
-// function array(items: unknown, extra?: Obj) {
-//   return { type: 'array', items, ...(extra ?? {}) }
-// }
-
-// function ref(name: string) {
-//   return { $ref: '#/components/schemas/' + name }
-// }
-
-// function jsonSchema(schema: string | Obj) {
-//   return {
-//     content: {
-//       'application/json': {
-//         schema: typeof schema === 'string' ? ref(schema) : schema,
-//       },
-//     },
-//   }
-// }
-
-// function route(params: {
-//   category: string
-//   describe: string
-//   path: string
-//   body?: string | Obj
-//   response?: string | Obj
-// }) {
-//   return {
-//     [params.path]: {
-//       post: {
-//         tags: [params.category],
-//         summary: params.describe,
-//         operationId: params.path,
-//         requestBody: params.body !== undefined ? jsonSchema(params.body) : undefined,
-//         responses: {
-//           default: {
-//             description: 'OK',
-//             ...jsonSchema(params.response ?? object({})),
-//           },
-//         },
-//       },
-//     },
-//   }
-// }
-
-// function response(schema: unknown) {
-//   return {
-//     type: 'object',
-//     properties: {
-//       success: boolean(undefined, { enum: [true] }),
-//       data: schema,
-//     },
-//   }
-// }
-
-// function pageResp(itemSchema: unknown) {
-//   return response({
-//     type: 'object',
-//     properties: {
-//       total: number(),
-//       list: array(itemSchema),
-//     },
-//   })
-// }
+import fsPromise from 'node:fs/promises'
+import path from 'node:path'
+import { getAbsoluteFSPath } from 'swagger-ui-dist'
+import { HTTPError } from '@/http/index.js'
+import type { Router, PathParameters, BaseContext } from '@/router/index.js'
+import { normalizePath } from '@/router/match.js'
+import * as factory from './factory.js'
+import type { OpenAPI } from './openapi-spec.js'
+
+export function registerSwaggerRoute(
+  router: Router,
+  endpoint: string = '/swagger',
+  customFields: OpenAPICustomFields = { info: { title: 'API Document', version: '0.0.1' } },
+  swaggerOptions?: Record<string, unknown>,
+) {
+  router.register({
+    category: 'swagger',
+    method: 'GET',
+    path: normalizePath(endpoint) + '/*',
+    handler: pageRoute.bind(null, swaggerOptions),
+  })
+  router.register({
+    category: 'swagger',
+    method: 'GET',
+    path: normalizePath(endpoint) + '/api-swagger.json',
+    handler: apiRoute.bind(null, router, customFields),
+  })
+}
+
+/**
+ * swagger 页面路由
+ */
+async function pageRoute(
+  swaggerOptions: Record<string, unknown> | undefined, // Example: { defaultModelsExpandDepth: 1, defaultModelExpandDepth: 1 }
+  { response }: BaseContext,
+  pathParameters: PathParameters,
+) {
+  const file = (pathParameters['*'] ?? '') || 'index.html'
+
+  const swaggerDir = getAbsoluteFSPath()
+  const abspath = path.join(swaggerDir, file)
+  if (!cache.has(abspath)) {
+    try {
+      const stat = await fsPromise.stat(abspath)
+      if (!stat.isFile()) throw new HTTPError(404)
+    } catch (e) {
+      throw new HTTPError(404)
+    }
+    const content = await fsPromise.readFile(abspath)
+    const replacemented = replacement(abspath, content, swaggerOptions)
+    cache.set(abspath, replacemented)
+  }
+  response.text(cache.get(abspath)!)
+}
+
+const cache = new Map<string, Buffer | string>()
+
+function replacement(abspath: string, content: Buffer, swaggerOptions?: Record<string, unknown>) {
+  if (/swagger-initializer.js/.exec(abspath)) {
+    let formatted = content
+      .toString()
+      .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json')
+    if (swaggerOptions) {
+      formatted = formatted.replace(
+        'SwaggerUIBundle({',
+        'SwaggerUIBundle({\n    ' + JSON.stringify(swaggerOptions).slice(1, -1) + ',\n',
+      )
+    }
+    return formatted
+  }
+  return content
+}
+
+/**
+ * swagger API 路由
+ */
+type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>
+
+function apiRoute(router: Router, customFields: OpenAPICustomFields, { response }: BaseContext) {
+  const swaggerJSON: OpenAPI = {
+    ...customFields,
+    openapi: '3.1.0',
+    paths: factory.paths(router.routes),
+    components: {
+      schemas: Object.entries(router.responseReferences).reduce(
+        (schemas, [name, type]) => ({ ...schemas, [name]: factory.responseSchema(type) }),
+        {},
+      ),
+    },
+  }
+  response.json(swaggerJSON)
+}

package/src/swagger/openapi-spec.ts

@@ -149,7 +149,7 @@ export interface Responses extends Extendable {
 }
 
 export interface Response extends Extendable {
-  descriptoin: CommonMark
+  description: CommonMark
   headers?: Record<string, Header | Reference>
   content?: Record<string, MediaType>
   links?: Record<string, Link | Reference>
@@ -185,8 +185,8 @@ export interface Tag extends Extendable {
 
 export interface Reference {
   $ref: string
-  summary: string
-  description: string
+  summary?: string
+  description?: string
 }
 
 export interface Schema extends Extendable {