@elysiajs/openapi 1.3.2

package/dist/swagger/types.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Swagger UI type because swagger-ui doesn't export an interface so here's copy paste
+ *
+ * @see swagger-ui/index.d.ts
+ **/
+export interface SwaggerUIOptions {
+    /**
+     * URL to fetch external configuration document from.
+     */
+    configUrl?: string | undefined;
+    /**
+     * REQUIRED if domNode is not provided. The ID of a DOM element inside which SwaggerUI will put its user interface.
+     */
+    dom_id?: string | undefined;
+    /**
+     * A JavaScript object describing the OpenAPI definition. When used, the url parameter will not be parsed. This is useful for testing manually-generated definitions without hosting them
+     */
+    spec?: {
+        [propName: string]: any;
+    } | undefined;
+    /**
+     * The URL pointing to API definition (normally swagger.json or swagger.yaml). Will be ignored if urls or spec is used.
+     */
+    url?: string | undefined;
+    /**
+     * An array of API definition objects ([{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}])
+     * used by Topbar plugin. When used and Topbar plugin is enabled, the url parameter will not be parsed.
+     * Names and URLs must be unique among all items in this array, since they're used as identifiers.
+     */
+    urls?: Array<{
+        url: string;
+        name: string;
+    }> | undefined;
+    /**
+     * The name of a component available via the plugin system to use as the top-level layout
+     * for Swagger UI.
+     */
+    layout?: string | undefined;
+    /**
+     * A Javascript object to configure plugin integration and behaviors
+     */
+    pluginsOptions?: PluginsOptions;
+    /**
+     * An array of plugin functions to use in Swagger UI.
+     */
+    plugins?: SwaggerUIPlugin[] | undefined;
+    /**
+     * An array of presets to use in Swagger UI.
+     * Usually, you'll want to include ApisPreset if you use this option.
+     */
+    presets?: SwaggerUIPlugin[] | undefined;
+    /**
+     * If set to true, enables deep linking for tags and operations.
+     * See the Deep Linking documentation for more information.
+     */
+    deepLinking?: boolean | undefined;
+    /**
+     * Controls the display of operationId in operations list. The default is false.
+     */
+    displayOperationId?: boolean | undefined;
+    /**
+     * The default expansion depth for models (set to -1 completely hide the models).
+     */
+    defaultModelsExpandDepth?: number | undefined;
+    /**
+     * The default expansion depth for the model on the model-example section.
+     */
+    defaultModelExpandDepth?: number | undefined;
+    /**
+     * Controls how the model is shown when the API is first rendered.
+     * (The user can always switch the rendering for a given model by clicking the
+     * 'Model' and 'Example Value' links.)
+     */
+    defaultModelRendering?: 'example' | 'model' | undefined;
+    /**
+     * Controls the display of the request duration (in milliseconds) for "Try it out" requests.
+     */
+    displayRequestDuration?: boolean | undefined;
+    /**
+     * Controls the default expansion setting for the operations and tags.
+     * It can be 'list' (expands only the tags), 'full' (expands the tags and operations)
+     * or 'none' (expands nothing).
+     */
+    docExpansion?: 'list' | 'full' | 'none' | undefined;
+    /**
+     * If set, enables filtering.
+     * The top bar will show an edit box that you can use to filter the tagged operations that are shown.
+     * Can be Boolean to enable or disable, or a string, in which case filtering will be enabled
+     * using that string as the filter expression.
+     * Filtering is case sensitive matching the filter expression anywhere inside the tag.
+     */
+    filter?: boolean | string | undefined;
+    /**
+     * If set, limits the number of tagged operations displayed to at most this many.
+     * The default is to show all operations.
+     */
+    maxDisplayedTags?: number | undefined;
+    /**
+     * Apply a sort to the operation list of each API.
+     * It can be 'alpha' (sort by paths alphanumerically),
+     * 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works).
+     * Default is the order returned by the server unchanged.
+     */
+    operationsSorter?: SorterLike | undefined;
+    /**
+     * Controls the display of vendor extension (x-) fields and values for Operations,
+     * Parameters, Responses, and Schema.
+     */
+    showExtensions?: boolean | undefined;
+    /**
+     * Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields
+     * and values for Parameters.
+     */
+    showCommonExtensions?: boolean | undefined;
+    /**
+     * Apply a sort to the tag list of each API.
+     * It can be 'alpha' (sort by paths alphanumerically)
+     * or a function (see Array.prototype.sort() to learn how to write a sort function).
+     * Two tag name strings are passed to the sorter for each pass.
+     * Default is the order determined by Swagger UI.
+     */
+    tagsSorter?: SorterLike | undefined;
+    /**
+     * When enabled, sanitizer will leave style, class and data-* attributes untouched
+     * on all HTML Elements declared inside markdown strings.
+     * This parameter is Deprecated and will be removed in 4.0.0.
+     * @deprecated
+     */
+    useUnsafeMarkdown?: boolean | undefined;
+    /**
+     * Provides a mechanism to be notified when Swagger UI has finished rendering a newly provided definition.
+     */
+    onComplete?: (() => any) | undefined;
+    /**
+     * Set to false to deactivate syntax highlighting of payloads and cURL command,
+     * can be otherwise an object with the activate and theme properties.
+     */
+    syntaxHighlight?: false | {
+        /**
+         * Whether syntax highlighting should be activated or not.
+         */
+        activate?: boolean | undefined;
+        /**
+         * Highlight.js syntax coloring theme to use. (Only these 6 styles are available.)
+         */
+        theme?: 'agate' | 'arta' | 'idea' | 'monokai' | 'nord' | 'obsidian' | 'tomorrow-night' | undefined;
+    } | undefined;
+    /**
+     * Controls whether the "Try it out" section should be enabled by default.
+     */
+    tryItOutEnabled?: boolean | undefined;
+    /**
+     * This is the default configuration section for the the requestSnippets plugin.
+     */
+    requestSnippets?: {
+        generators?: {
+            [genName: string]: {
+                title: string;
+                syntax: string;
+            };
+        } | undefined;
+        defaultExpanded?: boolean | undefined;
+        /**
+         * e.g. only show curl bash = ["curl_bash"]
+         */
+        languagesMask?: string[] | undefined;
+    } | undefined;
+    /**
+     * OAuth redirect URL.
+     */
+    oauth2RedirectUrl?: string | undefined;
+    /**
+     * MUST be a function. Function to intercept remote definition,
+     * "Try it out", and OAuth 2.0 requests.
+     * Accepts one argument requestInterceptor(request) and must return the modified request,
+     * or a Promise that resolves to the modified request.
+     */
+    requestInterceptor?: ((a: Request) => Request | Promise<Request>) | undefined;
+    /**
+     * MUST be a function. Function to intercept remote definition,
+     * "Try it out", and OAuth 2.0 responses.
+     * Accepts one argument responseInterceptor(response) and must return the modified response,
+     * or a Promise that resolves to the modified response.
+     */
+    responseInterceptor?: ((a: Response) => Response | Promise<Response>) | undefined;
+    /**
+     * If set to true, uses the mutated request returned from a requestInterceptor
+     * to produce the curl command in the UI, otherwise the request
+     * beforethe requestInterceptor was applied is used.
+     */
+    showMutatedRequest?: boolean | undefined;
+    /**
+     * List of HTTP methods that have the "Try it out" feature enabled.
+     * An empty array disables "Try it out" for all operations.
+     * This does not filter the operations from the display.
+     */
+    supportedSubmitMethods?: SupportedHTTPMethods[] | undefined;
+    /**
+     * By default, Swagger UI attempts to validate specs against swagger.io's online validator.
+     * You can use this parameter to set a different validator URL,
+     * for example for locally deployed validators (Validator Badge).
+     * Setting it to either none, 127.0.0.1 or localhost will disable validation.
+     */
+    validatorUrl?: string | undefined;
+    /**
+     * If set to true, enables passing credentials, as defined in the Fetch standard,
+     * in CORS requests that are sent by the browser.
+     * Note that Swagger UI cannot currently set cookies cross-domain (see swagger-js#1163)
+     * - as a result, you will have to rely on browser-supplied
+     * cookies (which this setting enables sending) that Swagger UI cannot control.
+     */
+    withCredentials?: boolean | undefined;
+    /**
+     * Function to set default values to each property in model.
+     * Accepts one argument modelPropertyMacro(property), property is immutable
+     */
+    modelPropertyMacro?: ((propName: Readonly<any>) => any) | undefined;
+    /**
+     * Function to set default value to parameters.
+     * Accepts two arguments parameterMacro(operation, parameter).
+     * Operation and parameter are objects passed for context, both remain immutable
+     */
+    parameterMacro?: ((operation: Readonly<any>, parameter: Readonly<any>) => any) | undefined;
+    /**
+     * If set to true, it persists authorization data and it would not be lost on browser close/refresh
+     */
+    persistAuthorization?: boolean | undefined;
+}
+interface PluginsOptions {
+    /**
+     * Control behavior of plugins when targeting the same component with wrapComponent.<br/>
+     * - `legacy` (default) : last plugin takes precedence over the others<br/>
+     * - `chain` : chain wrapComponents when targeting the same core component,
+     *  allowing multiple plugins to wrap the same component
+     * @default 'legacy'
+     */
+    pluginLoadType?: PluginLoadType;
+}
+type PluginLoadType = 'legacy' | 'chain';
+type SupportedHTTPMethods = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+type SorterLike = 'alpha' | 'method' | {
+    (name1: string, name2: string): number;
+};
+interface Request {
+    [prop: string]: any;
+}
+interface Response {
+    [prop: string]: any;
+}
+/**
+ * See https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/
+ */
+interface SwaggerUIPlugin {
+    (system: any): {
+        statePlugins?: {
+            [stateKey: string]: {
+                actions?: Indexable | undefined;
+                reducers?: Indexable | undefined;
+                selectors?: Indexable | undefined;
+                wrapActions?: Indexable | undefined;
+                wrapSelectors?: Indexable | undefined;
+            };
+        } | undefined;
+        components?: Indexable | undefined;
+        wrapComponents?: Indexable | undefined;
+        rootInjects?: Indexable | undefined;
+        afterLoad?: ((system: any) => any) | undefined;
+        fn?: Indexable | undefined;
+    };
+}
+interface Indexable {
+    [index: string]: any;
+}
+export {};

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+import type { TSchema } from 'elysia';
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ApiReferenceConfiguration } from '@scalar/types';
+import type { SwaggerUIOptions } from './swagger/types';
+export type OpenAPIProvider = 'scalar' | 'swagger-ui' | null;
+type MaybeArray<T> = T | T[];
+export type AdditionalReference = {
+    [path in string]: {
+        [method in string]: {
+            params: TSchema;
+            query: TSchema;
+            headers: TSchema;
+            body: TSchema;
+            response: {
+                [status in number]: TSchema;
+            };
+        };
+    };
+};
+export type AdditionalReferences = MaybeArray<AdditionalReference | undefined | (() => AdditionalReference | undefined)>;
+export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger', Provider extends OpenAPIProvider = 'scalar'> {
+    /**
+     * @default true
+     */
+    enabled?: Enabled;
+    /**
+     * OpenAPI config
+     *
+     * @see https://spec.openapis.org/oas/v3.0.3.html
+     */
+    documentation?: Omit<Partial<OpenAPIV3.Document>, 'x-express-openapi-additional-middleware' | 'x-express-openapi-validation-strict'>;
+    exclude?: {
+        /**
+         * Exclude methods from OpenAPI
+         */
+        methods?: string[];
+        /**
+         * Paths to exclude from OpenAPI endpoint
+         *
+         * @default []
+         */
+        paths?: string | RegExp | (string | RegExp)[];
+        /**
+         * Determine if OpenAPI should exclude static files.
+         *
+         * @default true
+         */
+        staticFile?: boolean;
+        /**
+         * Exclude tags from OpenAPI
+         */
+        tags?: string[];
+    };
+    /**
+     * The endpoint to expose OpenAPI Documentation
+     *
+     * @default '/openapi'
+     */
+    path?: Path;
+    /**
+     * Choose your provider, Scalar or Swagger UI
+     *
+     * @default 'scalar'
+     * @see https://github.com/scalar/scalar
+     * @see https://github.com/swagger-api/swagger-ui
+     */
+    provider?: Provider;
+    /**
+     * Additional reference for each endpoint
+     */
+    references?: AdditionalReferences;
+    /**
+     * Scalar configuration to customize scalar
+     *'
+     * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+     */
+    scalar?: ApiReferenceConfiguration & {
+        /**
+         * Version to use for Scalar cdn bundle
+         *
+         * @default 'latest'
+         * @see https://github.com/scalar/scalar
+         */
+        version?: string;
+        /**
+         * Optional override to specifying the path for the Scalar bundle
+         *
+         * Custom URL or path to locally hosted Scalar bundle
+         *
+         * Lease blank to use default jsdeliver.net CDN
+         *
+         * @default ''
+         * @example 'https://unpkg.com/@scalar/api-reference@1.13.10/dist/browser/standalone.js'
+         * @example '/public/standalone.js'
+         * @see https://github.com/scalar/scalar
+         */
+        cdn?: string;
+    };
+    /**
+     * The endpoint to expose OpenAPI JSON specification
+     *
+     * @default '/${path}/json'
+     */
+    specPath?: string;
+    /**
+     * Options to send to SwaggerUIBundle
+     * Currently, options that are defined as functions such as requestInterceptor
+     * and onComplete are not supported.
+     */
+    swagger?: Omit<Partial<SwaggerUIOptions>, 'dom_id' | 'dom_node' | 'spec' | 'url' | 'urls' | 'layout' | 'pluginsOptions' | 'plugins' | 'presets' | 'onComplete' | 'requestInterceptor' | 'responseInterceptor' | 'modelPropertyMacro' | 'parameterMacro'> & {
+        /**
+         * Custom Swagger CSS
+         */
+        theme?: string | {
+            light: string;
+            dark: string;
+        };
+        /**
+         * Version to use for swagger cdn bundle
+         *
+         * @see unpkg.com/swagger-ui-dist
+         *
+         * @default 4.18.2
+         */
+        version?: string;
+        /**
+         * Using poor man dark mode 😭
+         */
+        autoDarkMode?: boolean;
+        /**
+         * Optional override to specifying the path for the Swagger UI bundle
+         * Custom URL or path to locally hosted Swagger UI bundle
+         */
+        cdn?: string;
+    };
+}
+export {};

package/package.json

@@ -0,0 +1,92 @@
+{
+    "name": "@elysiajs/openapi",
+    "version": "1.3.2",
+    "description": "Plugin for Elysia to auto-generate API documentation",
+    "author": {
+        "name": "saltyAom",
+        "url": "https://github.com/SaltyAom",
+        "email": "saltyaom@gmail.com"
+    },
+    "main": "./dist/cjs/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/cjs/index.js"
+        },
+        "./gen": {
+        	"types": "./dist/gen/index.d.ts",
+			"import": "./dist/gen/index.mjs",
+			"require": "./dist/cjs/gen/index.js"
+        },
+        "./openapi": {
+            "types": "./dist/openapi.d.ts",
+            "import": "./dist/openapi.mjs",
+            "require": "./dist/cjs/openapi.js"
+        },
+        "./scalar": {
+            "types": "./dist/scalar/index.d.ts",
+            "import": "./dist/scalar/index.mjs",
+            "require": "./dist/cjs/scalar/index.js"
+        },
+        "./scalar/theme": {
+            "types": "./dist/scalar/theme.d.ts",
+            "import": "./dist/scalar/theme.mjs",
+            "require": "./dist/cjs/scalar/theme.js"
+        },
+        "./swagger": {
+            "types": "./dist/swagger/index.d.ts",
+            "import": "./dist/swagger/index.mjs",
+            "require": "./dist/cjs/swagger/index.js"
+        },
+        "./swagger/types": {
+            "types": "./dist/swagger/types.d.ts",
+            "import": "./dist/swagger/types.mjs",
+            "require": "./dist/cjs/swagger/types.js"
+        },
+        "./types": {
+            "types": "./dist/types.d.ts",
+            "import": "./dist/types.mjs",
+            "require": "./dist/cjs/types.js"
+        }
+    },
+    "keywords": [
+        "elysia",
+        "openapi",
+        "swagger",
+        "scalar"
+    ],
+    "homepage": "https://github.com/elysiajs/elysia-openapi",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/elysiajs/elysia-openapi"
+    },
+    "bugs": "https://github.com/elysiajs/elysia-openapi/issues",
+    "license": "MIT",
+    "scripts": {
+        "dev": "bun run --watch example/index.ts",
+        "test": "bun test && npm run test:node",
+        "test:node": "npm install --prefix ./test/node/cjs/ && npm install --prefix ./test/node/esm/ && node ./test/node/cjs/index.js && node ./test/node/esm/index.js",
+        "build": "bun build.ts",
+        "release": "npm run build && npm run test && npm publish --access public"
+    },
+    "peerDependencies": {
+        "elysia": ">= 1.3.0"
+    },
+    "devDependencies": {
+        "@apidevtools/swagger-parser": "^12.0.0",
+        "@types/bun": "1.2.20",
+        "@scalar/types": "^0.2.13",
+        "elysia": "1.3.21",
+        "eslint": "9.6.0",
+        "tsup": "^8.5.0",
+        "typescript": "^5.9.2"
+    },
+    "dependencies": {
+        "@sinclair/typemap": "^0.10.1",
+        "openapi-types": "^12.1.3"
+    }
+}