midway-scalar 1.0.0

package/README.md

@@ -0,0 +1,64 @@
+# midway-scalar
+
+Midway.js 组件，用于集成 Scalar API Reference，提供美观的 API 文档展示界面。
+
+## 功能特性
+
+- 集成 Scalar API Reference 到 Midway.js 应用
+- 自动读取 Swagger 配置生成 API 文档
+- 支持自定义 Scalar 配置选项
+- 提供 `/scalar` 路由访问 API 文档
+
+## 安装
+
+```bash
+npm install midway-scalar
+# 或
+pnpm add midway-scalar
+```
+
+## 使用
+
+### 1. 配置组件
+
+在 `src/configuration.ts` 中引入组件：
+
+```typescript
+import { Configuration } from '@midwayjs/core';
+import * as scalar from 'midway-scalar';
+
+@Configuration({
+  imports: [scalar],
+})
+export class MainConfiguration {}
+```
+
+### 2. 配置 Scalar
+
+在 `src/config/config.default.ts` 中配置：
+
+```typescript
+export default {
+  swagger: {
+    title: 'API 文档',
+    description: 'API 接口文档',
+    version: '1.0.0',
+  },
+  scalar: {
+    theme: 'purple',
+    darkMode: true,
+  },
+} as MidwayConfig;
+```
+
+### 3. 访问文档
+
+启动应用后，访问 `http://localhost:7001/scalar/` 查看 API 文档。
+
+## 配置选项
+
+更多配置选项请参考官方文档：[Scalar](https://guides.scalar.com/products/api-references/configuration#configuration__configuration-options)。
+
+## License
+
+MIT

package/dist/config/config.default.d.ts

@@ -0,0 +1 @@
+export declare const scalar: {};

package/dist/config/config.default.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scalar = void 0;
+exports.scalar = {};

package/dist/configuration.d.ts

@@ -0,0 +1,3 @@
+export declare class ScalarConfiguration {
+    onReady(): Promise<void>;
+}

package/dist/configuration.js

@@ -0,0 +1,29 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalarConfiguration = void 0;
+const core_1 = require("@midwayjs/core");
+const swagger = require("@midwayjs/swagger");
+const DefaultConfig = require("./config/config.default");
+let ScalarConfiguration = class ScalarConfiguration {
+    async onReady() {
+        // TODO something
+    }
+};
+ScalarConfiguration = __decorate([
+    (0, core_1.Configuration)({
+        namespace: 'scalar',
+        imports: [swagger],
+        importConfigs: [
+            {
+                default: DefaultConfig,
+            },
+        ],
+    })
+], ScalarConfiguration);
+exports.ScalarConfiguration = ScalarConfiguration;

package/dist/controller/scalar.controller.d.ts

@@ -0,0 +1,5 @@
+import { ScalarService } from '../service/scalar.service';
+export declare class ScalarController {
+    scalarService: ScalarService;
+    getApiReference(): Promise<string>;
+}

package/dist/controller/scalar.controller.js

@@ -0,0 +1,35 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalarController = void 0;
+const core_1 = require("@midwayjs/core");
+const swagger_1 = require("@midwayjs/swagger");
+const scalar_service_1 = require("../service/scalar.service");
+let ScalarController = class ScalarController {
+    async getApiReference() {
+        return this.scalarService.render();
+    }
+};
+__decorate([
+    (0, core_1.Inject)(),
+    __metadata("design:type", scalar_service_1.ScalarService)
+], ScalarController.prototype, "scalarService", void 0);
+__decorate([
+    (0, core_1.Get)('/'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], ScalarController.prototype, "getApiReference", null);
+ScalarController = __decorate([
+    (0, swagger_1.ApiExcludeController)(),
+    (0, core_1.Controller)('/scalar')
+], ScalarController);
+exports.ScalarController = ScalarController;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ScalarConfiguration as Configuration } from './configuration';
+export * from './controller/scalar.controller';
+export * from './interface';
+export * from './service/scalar.service';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Configuration = void 0;
+var configuration_1 = require("./configuration");
+Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_1.ScalarConfiguration; } });
+__exportStar(require("./controller/scalar.controller"), exports);
+__exportStar(require("./interface"), exports);
+__exportStar(require("./service/scalar.service"), exports);

package/dist/interface.d.ts

@@ -0,0 +1,157 @@
+export interface ScalarConfig {
+    url?: string;
+    content?: string | Record<string, any> | (() => Record<string, any>);
+    proxyUrl?: string;
+    authentication?: {
+        preferredSecurityScheme?: string | string[] | string[][];
+        securitySchemes?: {
+            [key: string]: {
+                name: string;
+                in: 'header' | 'query' | 'cookie';
+                value?: string;
+            } | {
+                token: string;
+            } | {
+                username: string;
+                password: string;
+            } | {
+                flows?: {
+                    authorizationCode?: {
+                        token?: string;
+                        'x-scalar-client-id'?: string;
+                        clientSecret?: string;
+                        authorizationUrl?: string;
+                        tokenUrl?: string;
+                        'x-scalar-redirect-uri'?: string;
+                        'x-usePkce'?: 'SHA-256' | 'plain' | 'no';
+                        selectedScopes?: string[];
+                        'x-scalar-security-query'?: Record<string, any>;
+                        'x-scalar-security-body'?: Record<string, any>;
+                        'x-tokenName'?: string;
+                        'x-scalar-credentials-location'?: 'header' | 'body';
+                    };
+                    clientCredentials?: {
+                        token?: string;
+                        'x-scalar-client-id'?: string;
+                        clientSecret?: string;
+                        tokenUrl?: string;
+                        selectedScopes?: string[];
+                        'x-tokenName'?: string;
+                        'x-scalar-credentials-location'?: 'header' | 'body';
+                    };
+                    implicit?: {
+                        token?: string;
+                        'x-scalar-client-id'?: string;
+                        authorizationUrl?: string;
+                        'x-scalar-redirect-uri'?: string;
+                        selectedScopes?: string[];
+                        'x-tokenName'?: string;
+                    };
+                    password?: {
+                        token?: string;
+                        'x-scalar-client-id'?: string;
+                        clientSecret?: string;
+                        tokenUrl?: string;
+                        username?: string;
+                        password?: string;
+                        selectedScopes?: string[];
+                        'x-tokenName'?: string;
+                        'x-scalar-credentials-location'?: 'header' | 'body';
+                    };
+                };
+                'x-default-scopes'?: string[];
+            };
+        };
+    };
+    baseServerURL?: string;
+    customCss?: string;
+    darkMode?: boolean;
+    defaultHttpClient?: {
+        targetKey: string;
+        clientKey: string;
+    };
+    defaultOpenAllTags?: boolean;
+    documentDownloadType?: 'json' | 'yaml' | 'both' | 'direct' | 'none';
+    expandAllModelSections?: boolean;
+    expandAllResponses?: boolean;
+    favicon?: string;
+    forceDarkModeState?: 'dark' | 'light';
+    hideClientButton?: boolean;
+    hideDarkModeToggle?: boolean;
+    showOperationId?: boolean;
+    hideModels?: boolean;
+    hideSearch?: boolean;
+    hideTestRequestButton?: boolean;
+    hiddenClients?: string[] | true | Record<string, boolean | string[]>;
+    isLoading?: boolean;
+    layout?: 'modern' | 'classic';
+    metaData?: Record<string, any>;
+    operationTitleSource?: 'summary' | 'path';
+    orderRequiredPropertiesFirst?: boolean;
+    orderSchemaPropertiesBy?: 'alpha' | 'preserve';
+    pathRouting?: {
+        basePath: string;
+    };
+    persistAuth?: boolean;
+    telemetry?: boolean;
+    plugins?: any[];
+    searchHotKey?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+        variables?: Record<string, {
+            default: string;
+            description?: string;
+            enum?: string[];
+        }>;
+    }>;
+    showSidebar?: boolean;
+    showDeveloperTools?: 'always' | 'localhost' | 'never';
+    theme?: string;
+    withDefaultFonts?: boolean;
+    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    generateHeadingSlug?: (heading: {
+        slug: string;
+        value: string;
+    }) => string;
+    generateModelSlug?: (model: {
+        name: string;
+    }) => string;
+    generateOperationSlug?: (operation: {
+        method: string;
+        path: string;
+        operationId?: string;
+        summary?: string;
+    }) => string;
+    generateTagSlug?: (tag: {
+        name: string;
+    }) => string;
+    generateWebhookSlug?: (webhook: {
+        name: string;
+        method?: string;
+    }) => string;
+    tagsSorter?: 'alpha' | ((a: {
+        name: string;
+    }, b: {
+        name: string;
+    }) => number);
+    operationsSorter?: 'alpha' | 'method' | ((a: {
+        method: string;
+        path: string;
+    }, b: {
+        method: string;
+        path: string;
+    }) => number);
+    redirect?: (path: string) => string | null | undefined;
+    onBeforeRequest?: ({ request }: {
+        request: Request;
+    }) => void | Promise<void>;
+    onDocumentSelect?: () => Promise<void> | void;
+    onLoaded?: (slug: string) => Promise<void> | void;
+    onRequestSent?: (request: string) => void;
+    onServerChange?: (server: string) => void;
+    onShowMore?: (tagId: string) => void | Promise<void>;
+    onSidebarClick?: (href: string) => void | Promise<void>;
+    onSpecUpdate?: (spec: string) => void;
+    [key: string]: any;
+}

package/dist/interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/service/scalar.service.d.ts

@@ -0,0 +1,5 @@
+import { MidwayConfig } from '@midwayjs/core';
+export declare class ScalarService {
+    config: MidwayConfig;
+    render(): Promise<string>;
+}

package/dist/service/scalar.service.js

@@ -0,0 +1,48 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalarService = void 0;
+const core_1 = require("@midwayjs/core");
+let ScalarService = class ScalarService {
+    async render() {
+        var _a;
+        const swaggerPath = ((_a = this.config.swagger) === null || _a === void 0 ? void 0 : _a.swaggerPath) || '/swagger-ui';
+        const specUrl = `${swaggerPath}/index.json`;
+        const scalarConfig = this.config.scalar;
+        const config = {
+            url: specUrl,
+            ...scalarConfig,
+        };
+        return `<!DOCTYPE html>
+<html>
+  <head>
+    <title>Scalar API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      Scalar.createApiReference('#app', ${JSON.stringify(config)});
+    </script>
+  </body>
+</html>`;
+    }
+};
+__decorate([
+    (0, core_1.Config)(core_1.ALL),
+    __metadata("design:type", Object)
+], ScalarService.prototype, "config", void 0);
+ScalarService = __decorate([
+    (0, core_1.Provide)()
+], ScalarService);
+exports.ScalarService = ScalarService;

package/index.d.ts

@@ -0,0 +1,8 @@
+export * from './dist/index';
+import { ScalarConfig } from './src/interface';
+
+declare module '@midwayjs/core/dist/interface' {
+  interface MidwayConfig {
+    scalar?: ScalarConfig;
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "midway-scalar",
+  "version": "1.0.0",
+  "description": "Midway.js component for Scalar API Reference integration",
+  "main": "dist/index.js",
+  "typings": "index.d.ts",
+  "scripts": {
+    "build": "mwtsc --cleanOutDir",
+    "test": "cross-env NODE_ENV=unittest jest",
+    "cov": "jest --coverage",
+    "lint": "mwts check",
+    "lint:fix": "mwts fix"
+  },
+  "keywords": ["midway", "scalar", "api-reference", "swagger", "openapi"],
+  "author": "nobu121",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "index.d.ts"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@midwayjs/core": "^3.12.0",
+    "@midwayjs/logger": "^3.1.0",
+    "@midwayjs/mock": "^3.12.0",
+    "@types/jest": "^29.2.0",
+    "@types/node": "^16.11.22",
+    "cross-env": "^6.0.0",
+    "jest": "^29.2.2",
+    "mwts": "^1.3.0",
+    "mwtsc": "^1.4.0",
+    "ts-jest": "^29.0.3",
+    "typescript": "~4.8.0"
+  },
+  "dependencies": {
+    "@midwayjs/swagger": "^3.20.19",
+    "@scalar/core": "^0.3.30"
+  }
+}