diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f5953c..6947c0b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# 1.1.1 - 12 Aug 2024 +Feature: +- add hide flag # 1.1.0 - 16 Jul 2024 Change: diff --git a/generated/index.d.ts b/generated/index.d.ts new file mode 100644 index 0000000..4934851 --- /dev/null +++ b/generated/index.d.ts @@ -0,0 +1,40 @@ +import { Elysia } from 'elysia'; +declare const app: Elysia<"", false, { + decorator: {}; + store: {}; + derive: {}; + resolve: {}; +}, { + type: {}; + error: {}; +}, { + schema: {}; + macro: {}; + macroFn: {}; +}, { + id: { + ":id?": { + get: { + body: unknown; + params: { + id?: string; + }; + query: unknown; + headers: unknown; + response: { + 200: "a"; + }; + }; + }; + }; +}, { + derive: {}; + resolve: {}; + schema: {}; +}, { + derive: {}; + resolve: {}; + schema: {}; +}>; +export type app = typeof app; +export {}; diff --git a/generated/plugin.d.ts b/generated/plugin.d.ts new file mode 100644 index 0000000..53e61ac --- /dev/null +++ b/generated/plugin.d.ts @@ -0,0 +1,107 @@ +import { Elysia } from 'elysia'; +export declare const plugin: Elysia<"/a", false, { + decorator: {}; + store: {}; + derive: {}; + resolve: {}; +}, { + type: { + readonly sign: { + username: string; + password: string; + }; + readonly number: number; + }; + error: {}; +}, { + schema: {}; + macro: {}; + macroFn: {}; +}, { + a: { + index: { + get: { + body: unknown; + params: {}; + query: unknown; + headers: unknown; + response: { + 200: string; + }; + }; + }; + }; +} & { + a: { + unpath: { + ":id": { + get: { + body: unknown; + params: { + id: string; + }; + query: unknown; + headers: unknown; + response: { + 200: string; + }; + }; + }; + }; + }; +} & { + a: { + json: { + post: { + body: unknown; + params: {}; + query: unknown; + headers: unknown; + response: { + 200: unknown; + }; + }; + }; + }; +} & { + a: { + json: { + ":id": { + post: { + body: unknown; + params: { + id: string; + }; + query: unknown; + headers: unknown; + response: { + 200: unknown; + 418: unknown; + }; + }; + }; + }; + }; +} & { + a: { + file: { + post: { + body: unknown; + params: {}; + query: unknown; + headers: unknown; + response: { + 200: unknown; + }; + }; + }; + }; +}, { + derive: {}; + resolve: {}; + schema: {}; +}, { + derive: {}; + resolve: {}; + schema: {}; +}>; diff --git a/package.json b/package.json index 9031870..65701d7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@elysiajs/swagger", - "version": "1.1.0", + "version": "1.1.1", "description": "Plugin for Elysia to auto-generate Swagger page", "author": { "name": "saltyAom", @@ -78,4 +78,4 @@ "lodash.clonedeep": "^4.5.0", "openapi-types": "^12.1.3" } -} \ No newline at end of file +} diff --git a/src/codegen.ts b/src/codegen.ts new file mode 100644 index 0000000..65d7d1e --- /dev/null +++ b/src/codegen.ts @@ -0,0 +1,23 @@ +// import { TypeScriptToModel, ModelToJsonSchema } from '@sinclair/typebox-codegen' +// import { cwd } from 'process' +// import { join } from 'path' + +// // await Bun.$` tsc example/index.ts --declaration --emitDeclarationOnly --esModuleInterop --skipLibCheck --declarationDir generated --rootDir example` + +// // Bun.file(join(cwd(), 'generated/index.d.ts')) + +// const type = TypeScriptToModel.Generate(` +// type A = { +// body: unknown; +// params: { +// id?: string; +// }; +// query: unknown; +// headers: unknown; +// response: { +// 200: "a"; +// }; +// } +// `) + +// console.dir(type, { depth: null }) diff --git a/src/index.d.ts b/src/index.d.ts new file mode 100644 index 0000000..77a71b9 --- /dev/null +++ b/src/index.d.ts @@ -0,0 +1,30 @@ +import { Elysia } from 'elysia'; +import type { ElysiaSwaggerConfig } from './types'; +/** + * Plugin for [elysia](https://github.com/elysiajs/elysia) that auto-generate Swagger page. + * + * @see https://github.com/elysiajs/elysia-swagger + */ +export declare const swagger: ({ provider, scalarVersion, scalarCDN, scalarConfig, documentation, version, excludeStaticFile, path, exclude, swaggerOptions, theme, autoDarkMode, excludeMethods, excludeTags }?: ElysiaSwaggerConfig) => Promise>; +export type { ElysiaSwaggerConfig }; +export default swagger; diff --git a/src/scalar/index.d.ts b/src/scalar/index.d.ts new file mode 100644 index 0000000..7bcb294 --- /dev/null +++ b/src/scalar/index.d.ts @@ -0,0 +1,2 @@ +import type { ReferenceConfiguration } from './types'; +export declare const ScalarRender: (version: string, config: ReferenceConfiguration, cdn: string) => string; diff --git a/src/scalar/theme.d.ts b/src/scalar/theme.d.ts new file mode 100644 index 0000000..cab26bb --- /dev/null +++ b/src/scalar/theme.d.ts @@ -0,0 +1,2 @@ +declare const _default: "\n/* basic theme */\n.light-mode {\n --theme-color-1: #2a2f45;\n --theme-color-2: #757575;\n --theme-color-3: #8e8e8e;\n --theme-color-accent: #f06292;\n\n --theme-background-1: #fff;\n --theme-background-2: #f6f6f6;\n --theme-background-3: #e7e7e7;\n --theme-background-accent: #f062921f;\n\n --theme-border-color: rgba(0, 0, 0, 0.1);\n}\n.dark-mode {\n --theme-color-1: rgba(255, 255, 255, 0.9);\n --theme-color-2: rgba(156, 163, 175, 1);\n --theme-color-3: rgba(255, 255, 255, 0.44);\n --theme-color-accent: #f06292;\n\n --theme-background-1: #111728;\n --theme-background-2: #1e293b;\n --theme-background-3: #334155;\n --theme-background-accent: #f062921f;\n\n --theme-border-color: rgba(255, 255, 255, 0.1);\n}\n/* Document Sidebar */\n.light-mode .sidebar,\n.dark-mode .sidebar {\n --sidebar-background-1: var(--theme-background-1);\n --sidebar-item-hover-color: currentColor;\n --sidebar-item-hover-background: var(--theme-background-2);\n --sidebar-item-active-background: var(--theme-background-accent);\n --sidebar-border-color: transparent;\n --sidebar-color-1: var(--theme-color-1);\n --sidebar-color-2: var(--theme-color-2);\n --sidebar-color-active: var(--theme-color-accent);\n --sidebar-search-background: transparent;\n --sidebar-search-border-color: var(--theme-border-color);\n --sidebar-search--color: var(--theme-color-3);\n}\n/* Document header only shows on mobile*/\n.dark-mode .t-doc__header,\n.light-mode .t-doc__header {\n --header-background-1: rgba(255, 255, 255, 0.85);\n --header-border-color: transparent;\n --header-color-1: var(--theme-color-1);\n --header-color-2: var(--theme-color-2);\n --header-background-toggle: var(--theme-color-3);\n --header-call-to-action-color: var(--theme-color-accent);\n}\n\n.dark-mode .t-doc__header {\n --header-background-1: rgba(17, 23, 40, 0.75);\n}\n\n/* advanced */\n.light-mode {\n --theme-button-1: rgb(49 53 56);\n --theme-button-1-color: #fff;\n --theme-button-1-hover: rgb(28 31 33);\n\n --theme-color-green: #069061;\n --theme-color-red: #ef0006;\n --theme-color-yellow: #edbe20;\n --theme-color-blue: #0082d0;\n --theme-color-orange: #fb892c;\n --theme-color-purple: #5203d1;\n\n --theme-scrollbar-color: rgba(0, 0, 0, 0.18);\n --theme-scrollbar-color-active: rgba(0, 0, 0, 0.36);\n}\n.dark-mode {\n --theme-button-1: #f6f6f6;\n --theme-button-1-color: #000;\n --theme-button-1-hover: #e7e7e7;\n\n --theme-color-green: #a3ffa9;\n --theme-color-red: #ffa3a3;\n --theme-color-yellow: #fffca3;\n --theme-color-blue: #a5d6ff;\n --theme-color-orange: #e2ae83;\n --theme-color-purple: #d2a8ff;\n\n --theme-scrollbar-color: rgba(255, 255, 255, 0.24);\n --theme-scrollbar-color-active: rgba(255, 255, 255, 0.48);\n}\n/* Elysia Specific */\n.scalar-api-client__send-request-button,\n.show-api-client-button {\n background: #3c82f6 !important;\n}\n.show-api-client-button:before {\n display: none;\n}\n\n.sidebar-search:hover {\n transition: all 0.15s ease-in-out;\n --sidebar-search-border-color: var(--theme-color-accent) !important;\n color: var(--sidebar-color-1) !important;\n}\n.scalar-api-client__container .sidebar {\n --sidebar-border-color: var(--theme-border-color);\n}\n@media (min-width: 1150px) {\n .section-container:has( ~ .footer):before,\n .tag-section-container:before {\n content: \"\";\n position: absolute;\n top: -5px;\n left: 0;\n width: 100%;\n height: 10px;\n background: linear-gradient(90deg, var(--theme-background-1) 3%,transparent 10%);\n }\n}\n.section-flare {\n position: absolute;\n width: 100vw;\n height: 300px;\n --stripes: repeating-linear-gradient(\n 100deg,\n #fff 0%,\n #fff 7%,\n transparent 10%,\n transparent 12%,\n #fff 16%\n );\n --stripesDark: repeating-linear-gradient(\n 100deg,\n #000 0%,\n #000 7%,\n transparent 10%,\n transparent 12%,\n #000 16%\n );\n --rainbow: repeating-linear-gradient(\n 100deg,\n #60a5fa 10%,\n #e879f9 16%,\n #5eead4 22%,\n #60a5fa 30%\n );\n background-image: var(--stripes), var(--rainbow);\n background-size: 300%, 200%;\n background-position: 50% 50%, 50% 50%;\n filter: invert(100%);\n -webkit-mask-image: radial-gradient(\n ellipse at 100% 0%,\n black 40%,\n transparent 70%\n );\n mask-image: radial-gradient(ellipse at 100% 0%, black 40%, transparent 70%);\n pointer-events: none;\n opacity: 0.15;\n}\n.dark-mode .section-flare {\n background-image: var(--stripesDark), var(--rainbow);\n filter: opacity(50%) saturate(200%);\n opacity: 0.25;\n}\n.section-flare:after {\n content: \"\";\n position: absolute;\n top: 0;\n right: 0;\n bottom: 0;\n left: 0;\n background-image: var(--stripes), var(--rainbow);\n background-size: 200%, 100%;\n background-attachment: fixed;\n mix-blend-mode: difference;\n}\n.dark-mode .section-flare:after {\n background-image: var(--stripesDark), var(--rainbow);\n}\n@keyframes headerbackground {\n from {\n background: transparent;\n backdrop-filter: none;\n }\n to {\n background: var(--header-background-1);\n backdrop-filter: blur(12px);\n }\n}\n.light-mode .t-doc__header,\n.dark-mode .t-doc__header {\n animation: headerbackground forwards;\n animation-timeline: scroll();\n animation-range: 0px 200px;\n --header-border-color: transparent;\n}\n"; +export default _default; diff --git a/src/scalar/types/index.d.ts b/src/scalar/types/index.d.ts new file mode 100644 index 0000000..6b18c23 --- /dev/null +++ b/src/scalar/types/index.d.ts @@ -0,0 +1,34 @@ +import type { MetaFlatInput } from "./unjead"; +export type ReferenceConfiguration = { + /** A string to use one of the color presets */ + theme?: ThemeId; + /** The layout to use for the references */ + layout?: ReferenceLayoutType; + /** The Swagger/OpenAPI spec to render */ + spec?: SpecConfiguration; + /** URL to a request proxy for the API client */ + proxy?: string; + /** Whether the spec input should show */ + isEditable?: boolean; + /** Whether to show the sidebar */ + showSidebar?: boolean; + /** Remove the Scalar branding :( */ + /** Key used with CNTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k) */ + searchHotKey?: string; + /** If used, passed data will be added to the HTML header. Read more: https://unhead.unjs.io/usage/composables/use-seo-meta */ + metaData?: MetaFlatInput; + /** Custom CSS to be added to the page */ + customCss?: string; + /** onSpecUpdate is fired on spec/swagger content change */ + onSpecUpdate?: (spec: string) => void; +}; +export type SpecConfiguration = { + /** URL to a Swagger/OpenAPI file */ + url?: string; + /** Swagger/Open API spec */ + content?: string | Record | (() => Record); + /** The result of @scalar/swagger-parser */ + preparsedContent?: Record; +}; +export type ReferenceLayoutType = 'modern' | 'classic'; +export type ThemeId = 'alternate' | 'default' | 'moon' | 'purple' | 'solarized' | 'none'; diff --git a/src/scalar/types/unjead.d.ts b/src/scalar/types/unjead.d.ts new file mode 100644 index 0000000..4df2ab1 --- /dev/null +++ b/src/scalar/types/unjead.d.ts @@ -0,0 +1,981 @@ +type Booleanable = boolean | 'false' | 'true' | ''; +type Arrayable = T | Array; +type ReferrerPolicy = '' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url'; +interface MetaFlatArticle { + /** + * Writers of the article. + * @example ['https://example.com/some.html', 'https://example.com/one.html'] + */ + articleAuthor?: string[]; + /** + * When the article is out of date after. + * @example '1970-01-01T00:00:00.000Z' + */ + articleExpirationTime?: string; + /** + * When the article was last changed. + * @example '1970-01-01T00:00:00.000Z' + */ + articleModifiedTime?: string; + /** + * When the article was first published. + * @example '1970-01-01T00:00:00.000Z' + */ + articlePublishedTime?: string; + /** + * A high-level section name. + * @example 'Technology' + */ + articleSection?: string; + /** + * Tag words associated with this article. + * @example ['Apple', 'Steve Jobs] + */ + articleTag?: string[]; +} +interface MetaFlatBook { + /** + * Who wrote this book. + * @example ['https://example.com/some.html', 'https://example.com/one.html'] + */ + bookAuthor?: string[]; + /** + * The ISBN. + * @example '978-3-16-148410-0' + */ + bookIsbn?: string; + /** + * The date the book was released. + * @example '1970-01-01T00:00:00.000Z' + */ + bookReleaseDate?: string; + /** + * Tag words associated with this book. + * @example ['Apple', 'Steve Jobs] + */ + bookTag?: string[]; +} +interface MetaFlatProfile { + /** + * A name normally given to an individual by a parent or self-chosen. + */ + profileFirstName?: string; + /** + * Their gender. + */ + profileGender?: 'male' | 'female' | string; + /** + * A name inherited from a family or marriage and by which the individual is commonly known. + */ + profileLastName?: string; + /** + * A short unique string to identify them. + */ + profileUsername?: string; +} +interface MetaFlat extends MetaFlatArticle, MetaFlatBook, MetaFlatProfile { + /** + * This attribute declares the document's character encoding. + * If the attribute is present, its value must be an ASCII case-insensitive match for the string "utf-8", + * because UTF-8 is the only valid encoding for HTML5 documents. + * `` elements which declare a character encoding must be located entirely within the first 1024 bytes + * of the document. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-charset + */ + charset: 'utf-8' | (string & Record); + /** + * Use this tag to provide a short description of the page. + * In some situations, this description is used in the snippet shown in search results. + * + * @see https://developers.google.com/search/docs/advanced/appearance/snippet#meta-descriptions + */ + description: string; + /** + * Specifies one or more color schemes with which the document is compatible. + * The browser will use this information in tandem with the user's browser or device settings to determine what colors + * to use for everything from background and foregrounds to form controls and scrollbars. + * The primary use for `` is to indicate compatibility with—and order of preference + * for—light and dark color modes. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#normal + */ + colorScheme: 'normal' | 'light dark' | 'dark light' | 'only light' | (string & Record); + /** + * The name of the application running in the web page. + * + * Uses: + * - When adding the page to the home screen. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name + */ + applicationName: string; + /** + * The name of the document's author. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name + */ + author: string; + /** + * The name of the creator of the document, such as an organization or institution. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#other_metadata_names + */ + creator: string; + /** + * The name of the document's publisher. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#other_metadata_names + */ + publisher: string; + /** + * The identifier of the software that generated the page. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification + */ + generator: string; + /** + * Controls the HTTP Referer header of requests sent from the document. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification + */ + referrer: ReferrerPolicy; + /** + * This tag tells the browser how to render a page on a mobile device. + * Presence of this tag indicates to Google that the page is mobile friendly. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_other_specifications + */ + viewport: 'width=device-width, initial-scale=1.0' | string | Partial<{ + /** + * Defines the pixel width of the viewport that you want the web site to be rendered at. + */ + width: number | string | 'device-width'; + /** + * Defines the height of the viewport. Not used by any browser. + */ + height: number | string | 'device-height'; + /** + * Defines the ratio between the device width + * (device-width in portrait mode or device-height in landscape mode) and the viewport size. + * + * @minimum 0 + * @maximum 10 + */ + initialScale: '1.0' | number | (string & Record); + /** + * Defines the maximum amount to zoom in. + * It must be greater or equal to the minimum-scale or the behavior is undefined. + * Browser settings can ignore this rule and iOS10+ ignores it by default. + * + * @minimum 0 + * @maximum 10 + */ + maximumScale: number | string; + /** + * Defines the minimum zoom level. It must be smaller or equal to the maximum-scale or the behavior is undefined. + * Browser settings can ignore this rule and iOS10+ ignores it by default. + * + * @minimum 0 + * @maximum 10 + */ + minimumScale: number | string; + /** + * If set to no, the user is unable to zoom in the webpage. + * The default is yes. Browser settings can ignore this rule, and iOS10+ ignores it by default. + */ + userScalable: 'yes' | 'no'; + /** + * The auto value doesn't affect the initial layout viewport, and the whole web page is viewable. + * + * The contain value means that the viewport is scaled to fit the largest rectangle inscribed within the display. + * + * The cover value means that the viewport is scaled to fill the device display. + * It is highly recommended to make use of the safe area inset variables to ensure that important content + * doesn't end up outside the display. + */ + viewportFit: 'auto' | 'contain' | 'cover'; + }>; + /** + * Control the behavior of search engine crawling and indexing. + * + * @see https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag + */ + robots: 'noindex, nofollow' | 'index, follow' | string | Partial<{ + /** + * Allow search engines to index this page. + * + * Note: This is not officially supported by Google but is used widely. + */ + index: Booleanable; + /** + * Allow search engines to follow links on this page. + * + * Note: This is not officially supported by Google but is used widely. + */ + follow: Booleanable; + /** + * There are no restrictions for indexing or serving. + * This directive is the default value and has no effect if explicitly listed. + */ + all: Booleanable; + /** + * Do not show this page, media, or resource in search results. + * If you don't specify this directive, the page, media, or resource may be indexed and shown in search results. + */ + noindex: Booleanable; + /** + * Do not follow the links on this page. + * If you don't specify this directive, Google may use the links on the page to discover those linked pages. + */ + nofollow: Booleanable; + /** + * Equivalent to noindex, nofollow. + */ + none: Booleanable; + /** + * Do not show a cached link in search results. + * If you don't specify this directive, + * Google may generate a cached page and users may access it through the search results. + */ + noarchive: Booleanable; + /** + * Do not show a sitelinks search box in the search results for this page. + * If you don't specify this directive, Google may generate a search box specific to your site in search results, + * along with other direct links to your site. + */ + nositelinkssearchbox: Booleanable; + /** + * + * Do not show a text snippet or video preview in the search results for this page. + * A static image thumbnail (if available) may still be visible, when it results in a better user experience. + */ + nosnippet: Booleanable; + /** + * Google is allowed to index the content of a page if it's embedded in another + * page through iframes or similar HTML tags, in spite of a noindex directive. + * + * indexifembedded only has an effect if it's accompanied by noindex. + */ + indexifembedded: Booleanable; + /** + * Use a maximum of [number] characters as a textual snippet for this search result. + */ + maxSnippet: number | string; + /** + * Set the maximum size of an image preview for this page in a search results. + */ + maxImagePreview: 'none' | 'standard' | 'large'; + /** + * Use a maximum of [number] seconds as a video snippet for videos on this page in search results. + */ + maxVideoPreview: number | string; + /** + * Don't offer translation of this page in search results. + */ + notranslate: Booleanable; + /** + * Do not show this page in search results after the specified date/time. + */ + unavailable_after: string; + /** + * Do not index images on this page. + */ + noimageindex: Booleanable; + }>; + /** + * Special meta tag for controlling Google's indexing behavior. + * + * @see https://developers.google.com/search/docs/crawling-indexing/special-tags + */ + google: + /** + * When users search for your site, Google Search results sometimes display a search box specific to your site, + * along with other direct links to your site. This tag tells Google not to show the sitelinks search box. + */ + 'nositelinkssearchbox' | + /** + * Prevents various Google text-to-speech services from reading aloud web pages using text-to-speech (TTS). + */ + 'nopagereadaloud'; + /** + * Control how Google indexing works specifically for the googlebot crawler. + * + * @see https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag + */ + googlebot: + /** + * When Google recognizes that the contents of a page aren't in the language that the user likely wants to read, + * Google may provide a translated title link and snippet in search results. + */ + 'notranslate' | 'noimageindex' | 'noarchive' | 'nosnippet' | 'max-snippet' | 'max-image-preview' | 'max-video-preview'; + /** + * Control how Google indexing works specifically for the googlebot-news crawler. + * + * @see https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag + */ + googlebotNews: 'noindex' | 'nosnippet' | 'notranslate' | 'noimageindex'; + /** + * You can use this tag on the top-level page of your site to verify ownership for Search Console. + * + * @see https://developers.google.com/search/docs/crawling-indexing/special-tags + */ + googleSiteVerification: string; + /** + * Labels a page as containing adult content, to signal that it be filtered by SafeSearch results + * . + * @see https://developers.google.com/search/docs/advanced/guidelines/safesearch + */ + rating: 'adult'; + /** + * The canonical URL for your page. + * + * This should be the undecorated URL, without session variables, user identifying parameters, or counters. + * Likes and Shares for this URL will aggregate at this URL. + * + * For example: mobile domain URLs should point to the desktop version of the URL as the canonical URL to aggregate + * Likes and Shares across different versions of the page. + * + * @see https://ogp.me/#metadata + */ + ogUrl: string; + /** + * The title of your page without any branding such as your site name. + * + * @see https://ogp.me/#metadata + */ + ogTitle: string; + /** + * A brief description of the content, usually between 2 and 4 sentences. + * + * @see https://ogp.me/#optional + */ + ogDescription: string; + /** + * The type of media of your content. This tag impacts how your content shows up in Feed. If you don't specify a type, + * the default is website. + * Each URL should be a single object, so multiple og:type values are not possible. + * + * @see https://ogp.me/#metadata + */ + ogType: 'website' | 'article' | 'book' | 'profile' | 'music.song' | 'music.album' | 'music.playlist' | 'music.radio_status' | 'video.movie' | 'video.episode' | 'video.tv_show' | 'video.other'; + /** + * The locale of the resource. Defaults to en_US. + * + * @see https://ogp.me/#optional + */ + ogLocale: string; + /** + * An array of other locales this page is available in. + * + * @see https://ogp.me/#optional + */ + ogLocaleAlternate: Arrayable; + /** + * The word that appears before this object's title in a sentence. + * An enum of (a, an, the, "", auto). + * If auto is chosen, the consumer of your data should choose between "a" or "an". + * Default is "" (blank). + * + * @see https://ogp.me/#optional + */ + ogDeterminer: 'a' | 'an' | 'the' | '' | 'auto'; + /** + * If your object is part of a larger website, the name which should be displayed for the overall site. e.g., "IMDb". + * + * @see https://ogp.me/#optional + */ + ogSiteName: string; + /** + * The URL for the video. If you want the video to play in-line in Feed, you should use the https:// URL if possible. + * + * @see https://ogp.me/#type_video + */ + ogVideo: string | Arrayable<{ + /** + * Equivalent to og:video + */ + url: string; + /** + * + * Secure URL for the video. Include this even if you set the secure URL in og:video. + */ + secureUrl?: string; + /** + * MIME type of the video. + */ + type?: 'application/x-shockwave-flash' | 'video/mp4'; + /** + * Width of video in pixels. This property is required for videos. + */ + width?: string | number; + /** + * Height of video in pixels. This property is required for videos. + */ + height?: string | number; + /** + * A text description of the video. + */ + alt?: string; + }>; + /** + * Equivalent to og:video + * + * @see https://ogp.me/#type_video + */ + ogVideoUrl: string; + /** + * + * Secure URL for the video. Include this even if you set the secure URL in og:video. + * + * @see https://ogp.me/#type_video + */ + ogVideoSecureUrl: string; + /** + * MIME type of the video. + * + * @see https://ogp.me/#type_video + */ + ogVideoType: 'application/x-shockwave-flash' | 'video/mp4'; + /** + * Width of video in pixels. This property is required for videos. + * + * @see https://ogp.me/#type_video + */ + ogVideoWidth: string | number; + /** + * Height of video in pixels. This property is required for videos. + * + * @see https://ogp.me/#type_video + */ + ogVideoHeight: string | number; + /** + * A text description of the video. + * + * @see https://ogp.me/#type_video + */ + ogVideoAlt: string; + /** + * The URL of the image that appears when someone shares the content. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImage: string | Arrayable<{ + /** + * Equivalent to og:image + */ + url: string; + /** + * + * https:// URL for the image + */ + secureUrl?: string; + /** + * MIME type of the image. + */ + type?: 'image/jpeg' | 'image/gif' | 'image/png'; + /** + * Width of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + */ + width?: '1200' | string | number; + /** + * Height of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + */ + height?: '630' | string | number; + /** + * A description of what is in the image (not a caption). If the page specifies an og:image, it should specify og:image:alt. + */ + alt?: string; + }>; + /** + * Equivalent to og:image + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageUrl: string; + /** + * + * https:// URL for the image + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageSecureUrl: string; + /** + * MIME type of the image. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageType: 'image/jpeg' | 'image/gif' | 'image/png'; + /** + * Width of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageWidth: '1200' | string | number; + /** + * Height of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageHeight: '630' | string | number; + /** + * A description of what is in the image (not a caption). If the page specifies an og:image, it should specify og:image:alt. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#images + */ + ogImageAlt: string; + /** + * The URL for an audio file to accompany this object. + * + * @see https://ogp.me/#optional + */ + ogAudio: string | Arrayable<{ + /** + * Equivalent to og:audio + */ + url: string; + /** + * Secure URL for the audio. Include this even if you set the secure URL in og:audio. + */ + secureUrl?: string; + /** + * MIME type of the audio. + */ + type?: 'audio/mpeg' | 'audio/ogg' | 'audio/wav'; + }>; + /** + * Equivalent to og:audio + * + * @see https://ogp.me/#optional + */ + ogAudioUrl: string; + /** + * Secure URL for the audio. Include this even if you set the secure URL in og:audio. + * + * @see https://ogp.me/#optional + */ + ogAudioSecureUrl: string; + /** + * MIME type of the audio. + * + * @see https://ogp.me/#optional + */ + ogAudioType: 'audio/mpeg' | 'audio/ogg' | 'audio/wav'; + /** + * Your Facebook app ID. + * + * In order to use Facebook Insights you must add the app ID to your page. + * Insights lets you view analytics for traffic to your site from Facebook. Find the app ID in your App Dashboard. + * + * @see https://developers.facebook.com/docs/sharing/webmasters#basic + */ + fbAppId: string | number; + /** + * The card type + * + * Used with all cards + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterCard: 'summary' | 'summary_large_image' | 'app' | 'player'; + /** + * Title of content (max 70 characters) + * + * Used with summary, summary_large_image, player cards + * + * Same as `og:title` + * + * @maxLength 70 + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterTitle: string; + /** + * Description of content (maximum 200 characters) + * + * Used with summary, summary_large_image, player cards. + * + * Same as `og:description` + * + * @maxLength 200 + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterDescription: string; + /** + * URL of image to use in the card. + * Images must be less than 5MB in size. + * JPG, PNG, WEBP and GIF formats are supported. + * Only the first frame of an animated GIF will be used. SVG is not supported. + * + * Used with summary, summary_large_image, player cards + * + * Same as `og:image`. + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterImage: string | Arrayable<{ + /** + * Equivalent to twitter:image + */ + url: string; + /** + * MIME type of the image. + * @deprecated Twitter removed this property from their card specification. + */ + type?: 'image/jpeg' | 'image/gif' | 'image/png'; + /** + * Width of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + * @deprecated Twitter removed this property from their card specification. + */ + width?: '1200' | string | number; + /** + * Height of image in pixels. Specify height and width for your image to ensure that the image loads properly the first time it's shared. + * @deprecated Twitter removed this property from their card specification. + */ + height?: '630' | string | number; + /** + * A description of what is in the image (not a caption). If the page specifies an og:image, it should specify og:image:alt. + */ + alt?: string; + }>; + /** + * The width of the image in pixels. + * + * Note: This is not officially documented. + * + * Same as `og:image:width` + * + * @deprecated Twitter removed this property from their card specification. + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterImageWidth: string | number; + /** + * The height of the image in pixels. + * + * Note: This is not officially documented. + * + * Same as `og:image:height` + * + * @deprecated Twitter removed this property from their card specification. + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterImageHeight: string | number; + /** + * The type of the image. + * + * Note: This is not officially documented. + * + * Same as `og:image:type` + * + * @deprecated Twitter removed this property from their card specification. + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterImageType: 'image/jpeg' | 'image/gif' | 'image/png'; + /** + * A text description of the image conveying the essential nature of an image to users who are visually impaired. + * Maximum 420 characters. + * + * Used with summary, summary_large_image, player cards + * + * Same as `og:image:alt`. + * + * @maxLength 420 + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards + */ + twitterImageAlt: string; + /** + * The @username of website. Either twitter:site or twitter:site:id is required. + * + * Used with summary, summary_large_image, app, player cards + * + * @example @harlan_zw + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterSite: string; + /** + * Same as twitter:site, but the user’s Twitter ID. Either twitter:site or twitter:site:id is required. + * + * Used with summary, summary_large_image, player cards + * + * @example 1296047337022742529 + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterSiteId: string | number; + /** + * The @username who created the pages content. + * + * Used with summary_large_image cards + * + * @example harlan_zw + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterCreator: string; + /** + * Twitter user ID of content creator + * + * Used with summary, summary_large_image cards + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterCreatorId: string | number; + /** + * HTTPS URL of player iframe + * + * Used with player card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterPlayer: string; + /** + * + * Width of iframe in pixels + * + * Used with player card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterPlayerWidth: string | number; + /** + * Height of iframe in pixels + * + * Used with player card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterPlayerHeight: string | number; + /** + * URL to raw video or audio stream + * + * Used with player card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterPlayerStream: string; + /** + * Name of your iPhone app + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppNameIphone: string; + /** + * Your app ID in the iTunes App Store + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppIdIphone: string; + /** + * Your app’s custom URL scheme (you must include ”://” after your scheme name) + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppUrlIphone: string; + /** + * Name of your iPad optimized app + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppNameIpad: string; + /** + * Your app ID in the iTunes App Store + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppIdIpad: string; + /** + * Your app’s custom URL scheme + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppUrlIpad: string; + /** + * Name of your Android app + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppNameGoogleplay: string; + /** + * Your app ID in the Google Play Store + * + * Used with app card + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppIdGoogleplay: string; + /** + * Your app’s custom URL scheme + * + * @see https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup + */ + twitterAppUrlGoogleplay: string; + /** + * Top customizable data field, can be a relatively short string (ie “$3.99”) + * + * Used by Slack. + * + * @see https://api.slack.com/reference/messaging/link-unfurling#classic_unfurl + */ + twitterData1: string; + /** + * Customizable label or units for the information in twitter:data1 (best practice: use all caps) + * + * Used by Slack. + * + * @see https://api.slack.com/reference/messaging/link-unfurling#classic_unfurl + */ + twitterLabel1: string; + /** + * Bottom customizable data field, can be a relatively short string (ie “Seattle, WA”) + * + * Used by Slack. + * + * @see https://api.slack.com/reference/messaging/link-unfurling#classic_unfurl + */ + twitterData2: string; + /** + * Customizable label or units for the information in twitter:data2 (best practice: use all caps) + * + * Used by Slack. + * + * @see https://api.slack.com/reference/messaging/link-unfurling#classic_unfurl + */ + twitterLabel2: string; + /** + * Indicates a suggested color that user agents should use to customize the display of the page or + * of the surrounding user interface. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name + * @example `#4285f4` or `{ color: '#4285f4', media: '(prefers-color-scheme: dark)'}` + */ + themeColor: string | Arrayable<{ + /** + * A valid CSS color value that matches the value used for the `theme-color` CSS property. + * + * @example `#4285f4` + */ + content: string; + /** + * A valid media query that defines when the value should be used. + * + * @example `(prefers-color-scheme: dark)` + */ + media: '(prefers-color-scheme: dark)' | '(prefers-color-scheme: light)' | string; + }>; + /** + * Sets whether a web application runs in full-screen mode. + */ + mobileWebAppCapable: 'yes'; + /** + * Sets whether a web application runs in full-screen mode. + * + * @see https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html + */ + appleMobileWebAppCapable: 'yes'; + /** + * Sets the style of the status bar for a web application. + * + * @see https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html + */ + appleMobileWebAppStatusBarStyle: 'default' | 'black' | 'black-translucent'; + /** + * Make the app title different from the page title. + */ + appleMobileWebAppTitle: string; + /** + * Promoting Apps with Smart App Banners + * + * @see https://developer.apple.com/documentation/webkit/promoting_apps_with_smart_app_banners + */ + appleItunesApp: string | { + /** + * Your app’s unique identifier. + */ + appId: string; + /** + * A URL that provides context to your native app. + */ + appArgument?: string; + }; + /** + * Enables or disables automatic detection of possible phone numbers in a webpage in Safari on iOS. + * + * @see https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html + */ + formatDetection: 'telephone=no'; + /** + * Tile image for windows. + * + * @see https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85) + */ + msapplicationTileImage: string; + /** + * Tile colour for windows + * + * @see https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85) + */ + msapplicationTileColor: string; + /** + * URL of a config for windows tile. + * + * @see https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85) + */ + msapplicationConfig: string; + contentSecurityPolicy: string | Partial<{ + childSrc: string; + connectSrc: string; + defaultSrc: string; + fontSrc: string; + imgSrc: string; + manifestSrc: string; + mediaSrc: string; + objectSrc: string; + prefetchSrc: string; + scriptSrc: string; + scriptSrcElem: string; + scriptSrcAttr: string; + styleSrc: string; + styleSrcElem: string; + styleSrcAttr: string; + workerSrc: string; + baseUri: string; + sandbox: string; + formAction: string; + frameAncestors: string; + reportUri: string; + reportTo: string; + requireSriFor: string; + requireTrustedTypesFor: string; + trustedTypes: string; + upgradeInsecureRequests: string; + }>; + contentType: 'text/html; charset=utf-8'; + defaultStyle: string; + xUaCompatible: 'IE=edge'; + refresh: string | { + seconds: number | string; + url: string; + }; + /** + * A comma-separated list of keywords - relevant to the page (Legacy tag used to tell search engines what the page is about). + * @deprecated the "keywords" metatag is no longer used. + * @see https://web.dev/learn/html/metadata/#keywords + */ + keywords: string; +} +type MetaFlatNullable = { + [K in keyof MetaFlat]: MetaFlat[K] | null; +}; +export type MetaFlatInput = Partial; +export {}; diff --git a/src/swagger/index.d.ts b/src/swagger/index.d.ts new file mode 100644 index 0000000..1a0fed3 --- /dev/null +++ b/src/swagger/index.d.ts @@ -0,0 +1,5 @@ +import type { OpenAPIV3 } from 'openapi-types'; +export declare const SwaggerUIRender: (info: OpenAPIV3.InfoObject, version: string, theme: string | { + light: string; + dark: string; +}, stringifiedSwaggerOptions: string, autoDarkMode?: boolean) => string; diff --git a/src/swagger/types.d.ts b/src/swagger/types.d.ts new file mode 100644 index 0000000..a82f415 --- /dev/null +++ b/src/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: "", name: ""},{url: "", name: ""}]) + * 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) | 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) | 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) | 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, parameter: Readonly) => 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.
+ * - `legacy` (default) : last plugin takes precedence over the others
+ * - `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 {}; diff --git a/src/types.d.ts b/src/types.d.ts new file mode 100644 index 0000000..5dc906c --- /dev/null +++ b/src/types.d.ts @@ -0,0 +1,96 @@ +import type { OpenAPIV3 } from 'openapi-types'; +import type { ReferenceConfiguration } from './scalar/types'; +import type { SwaggerUIOptions } from './swagger/types'; +export interface ElysiaSwaggerConfig { + /** + * Customize Swagger config, refers to Swagger 2.0 config + * + * @see https://swagger.io/specification/v2/ + */ + documentation?: Omit, 'x-express-openapi-additional-middleware' | 'x-express-openapi-validation-strict'>; + /** + * Choose your provider, Scalar or Swagger UI + * + * @default 'scalar' + * @see https://github.com/scalar/scalar + * @see https://github.com/swagger-api/swagger-ui + */ + provider?: 'scalar' | 'swagger-ui'; + /** + * Version to use for Scalar cdn bundle + * + * @default 'latest' + * @see https://github.com/scalar/scalar + */ + scalarVersion?: 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 + */ + scalarCDN?: string; + /** + * Scalar configuration to customize scalar + *' + * @see https://github.com/scalar/scalar + */ + scalarConfig?: ReferenceConfiguration; + /** + * Version to use for swagger cdn bundle + * + * @see unpkg.com/swagger-ui-dist + * + * @default 4.18.2 + */ + version?: string; + /** + * Determine if Swagger should exclude static files. + * + * @default true + */ + excludeStaticFile?: boolean; + /** + * The endpoint to expose Swagger + * + * @default '/swagger' + */ + path?: Path; + /** + * Paths to exclude from Swagger endpoint + * + * @default [] + */ + exclude?: string | RegExp | (string | RegExp)[]; + /** + * Options to send to SwaggerUIBundle + * Currently, options that are defined as functions such as requestInterceptor + * and onComplete are not supported. + */ + swaggerOptions?: Omit, '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; + }; + /** + * Using poor man dark mode 😭 + */ + autoDarkMode?: boolean; + /** + * Exclude methods from Swagger + */ + excludeMethods?: string[]; + /** + * Exclude tags from Swagger or Scalar + */ + excludeTags?: string[]; +} diff --git a/src/utils.d.ts b/src/utils.d.ts new file mode 100644 index 0000000..6c2ff66 --- /dev/null +++ b/src/utils.d.ts @@ -0,0 +1,26 @@ +import type { HTTPMethod, LocalHook } from 'elysia'; +import { type TSchema } from '@sinclair/typebox'; +import type { OpenAPIV3 } from 'openapi-types'; +export declare const toOpenAPIPath: (path: string) => string; +export declare const mapProperties: (name: string, schema: TSchema | string | undefined, models: Record) => { + description: any; + examples: any; + schema: any; + in: string; + name: string; + required: any; +}[]; +export declare const capitalize: (word: string) => string; +export declare const generateOperationId: (method: string, paths: string) => string; +export declare const registerSchemaPath: ({ schema, path, method, hook, models }: { + schema: Partial; + contentType?: string | string[]; + path: string; + method: HTTPMethod; + hook?: LocalHook; + models: Record; +}) => void; +export declare const filterPaths: (paths: Record, docsPath: string, { excludeStaticFile, exclude }: { + excludeStaticFile: boolean; + exclude: (string | RegExp)[]; +}) => Record;