@hestjs/scalar 0.1.0

package/dist/utils/index.js

@@ -0,0 +1,212 @@
+/**
+ * 生成基础 OpenAPI 文档结构
+ */
+export function generateBaseOpenApiSpec(config) {
+    return {
+        openapi: '3.0.0',
+        info: {
+            title: config.title,
+            version: config.version,
+            description: config.description || `${config.title} API Documentation`,
+        },
+        servers: config.servers || [
+            {
+                url: 'http://localhost:3000',
+                description: 'Development server',
+            },
+        ],
+        paths: {},
+        components: {
+            schemas: {},
+            responses: {},
+            parameters: {},
+            securitySchemes: {},
+        },
+    };
+}
+/**
+ * 从类元数据生成 OpenAPI schema
+ */
+export function generateSchemaFromClass(target) {
+    const properties = Reflect.getMetadata('api:properties', target) || {};
+    const schema = {
+        type: 'object',
+        properties: {},
+    };
+    const required = [];
+    for (const [propertyKey, metadata] of Object.entries(properties)) {
+        const propMetadata = metadata;
+        schema.properties[propertyKey] = {
+            type: getTypeString(propMetadata.type),
+            description: propMetadata.description,
+            example: propMetadata.example,
+        };
+        if (propMetadata.enum) {
+            schema.properties[propertyKey].enum = propMetadata.enum;
+        }
+        if (propMetadata.required) {
+            required.push(propertyKey);
+        }
+    }
+    if (required.length > 0) {
+        schema.required = required;
+    }
+    return schema;
+}
+/**
+ * 从控制器生成 OpenAPI 路径
+ */
+export function generatePathsFromController(controller, basePath = '') {
+    const paths = {};
+    const controllerTags = Reflect.getMetadata('api:tags', controller) || [];
+    // 获取控制器的所有方法
+    const prototype = controller.prototype;
+    const methodNames = Object.getOwnPropertyNames(prototype).filter(name => name !== 'constructor' && typeof prototype[name] === 'function');
+    for (const methodName of methodNames) {
+        const routeMetadata = Reflect.getMetadata('route', prototype, methodName);
+        if (!routeMetadata)
+            continue;
+        const { method, path } = routeMetadata;
+        const fullPath = `${basePath}${path}`;
+        if (!paths[fullPath]) {
+            paths[fullPath] = {};
+        }
+        const operation = generateOperationFromMethod(controller, methodName, controllerTags);
+        paths[fullPath][method.toLowerCase()] = operation;
+    }
+    return paths;
+}
+/**
+ * 从方法生成 OpenAPI 操作
+ */
+function generateOperationFromMethod(controller, methodName, tags) {
+    const prototype = controller.prototype;
+    const operation = {
+        tags,
+    };
+    // 获取操作元数据
+    const operationMetadata = Reflect.getMetadata('api:operation', prototype, methodName);
+    if (operationMetadata) {
+        operation.summary = operationMetadata.summary;
+        operation.description = operationMetadata.description;
+        operation.operationId = operationMetadata.operationId || `${controller.name}_${methodName}`;
+    }
+    // 获取参数元数据
+    const parametersMetadata = Reflect.getMetadata('api:parameters', controller) || {};
+    if (parametersMetadata[methodName]) {
+        operation.parameters = parametersMetadata[methodName].map((param) => ({
+            name: param.name,
+            in: param.in,
+            description: param.description,
+            required: param.required || param.in === 'path',
+            schema: {
+                type: getTypeString(param.type),
+                example: param.example,
+            },
+        }));
+    }
+    // 获取请求体元数据
+    const bodyMetadata = Reflect.getMetadata('api:body', prototype, methodName);
+    if (bodyMetadata) {
+        operation.requestBody = {
+            description: bodyMetadata.description,
+            required: bodyMetadata.required,
+            content: {
+                'application/json': {
+                    schema: bodyMetadata.type ? generateSchemaFromClass(bodyMetadata.type) : {},
+                },
+            },
+        };
+    }
+    // 获取响应元数据
+    const responsesMetadata = Reflect.getMetadata('api:responses', controller) || {};
+    if (responsesMetadata[methodName]) {
+        operation.responses = {};
+        for (const response of responsesMetadata[methodName]) {
+            operation.responses[response.status] = {
+                description: response.description,
+                content: response.type ? {
+                    'application/json': {
+                        schema: response.schema || generateSchemaFromClass(response.type),
+                    },
+                } : undefined,
+            };
+        }
+    }
+    else {
+        // 默认响应
+        operation.responses = {
+            200: {
+                description: 'Success',
+            },
+        };
+    }
+    return operation;
+}
+/**
+ * 获取类型字符串
+ */
+function getTypeString(type) {
+    if (!type)
+        return 'string';
+    if (type === String)
+        return 'string';
+    if (type === Number)
+        return 'number';
+    if (type === Boolean)
+        return 'boolean';
+    if (type === Date)
+        return 'string';
+    if (Array.isArray(type))
+        return 'array';
+    return 'object';
+}
+/**
+ * 合并多个 OpenAPI 文档
+ */
+export function mergeOpenApiSpecs(...specs) {
+    const merged = {
+        openapi: '3.0.0',
+        info: {},
+        servers: [],
+        paths: {},
+        components: {
+            schemas: {},
+            responses: {},
+            parameters: {},
+            securitySchemes: {},
+        },
+    };
+    for (const spec of specs) {
+        const specObj = spec;
+        // 合并基本信息（使用第一个非空的）
+        if (specObj.info && !merged.info.title) {
+            merged.info = { ...specObj.info };
+        }
+        // 合并服务器
+        if (specObj.servers) {
+            merged.servers.push(...specObj.servers);
+        }
+        // 合并路径
+        if (specObj.paths) {
+            Object.assign(merged.paths, specObj.paths);
+        }
+        // 合并组件
+        if (specObj.components) {
+            if (specObj.components.schemas) {
+                Object.assign(merged.components.schemas, specObj.components.schemas);
+            }
+            if (specObj.components.responses) {
+                Object.assign(merged.components.responses, specObj.components.responses);
+            }
+            if (specObj.components.parameters) {
+                Object.assign(merged.components.parameters, specObj.components.parameters);
+            }
+            if (specObj.components.securitySchemes) {
+                Object.assign(merged.components.securitySchemes, specObj.components.securitySchemes);
+            }
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@hestjs/scalar",
+  "version": "0.1.0",
+  "description": "HestJS Scalar API Reference Integration - Beautiful API documentation for HestJS applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build",
+    "publish:npm": "npm publish --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aqz236/hest.git"
+  },
+  "homepage": "https://github.com/aqz236/hest#readme",
+  "bugs": {
+    "url": "https://github.com/aqz236/hest/issues"
+  },
+  "author": "aqz236",
+  "license": "MIT",
+  "dependencies": {
+    "@hestjs/core": "0.1.8",
+    "@scalar/hono-api-reference": "^0.5.173",
+    "@scalar/openapi-to-markdown": "^0.1.2",
+    "@scalar/themes": "^0.13.11",
+    "hono": "^4.8.9"
+  },
+  "optionalDependencies": {
+    "@scalar/hono-api-reference": "^0.9.12",
+    "@scalar/openapi-to-markdown": "^0.2.23",
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "typescript": "5.8.3"
+  },
+  "peerDependencies": {
+    "@hestjs/core": ">=0.1.0",
+    "hono": ">=4.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "hestjs",
+    "scalar",
+    "api-reference",
+    "openapi",
+    "swagger",
+    "documentation",
+    "hono",
+    "typescript"
+  ]
+}