npm - @scalar/api-reference - Versions diffs - 1.24.15 → 1.24.17 - Mend

@scalar/api-reference 1.24.15 → 1.24.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/CHANGELOG.md +29 -0
package/README.md +84 -249
package/dist/browser/standalone.js +16598 -13496
package/dist/browser/webpack-stats.json +1 -1
package/dist/components/ApiClientModal.vue.js +26 -0
package/dist/components/ApiClientModal.vue2.js +4 -0
package/dist/components/ApiReferenceLayout.vue.d.ts.map +1 -1
package/dist/components/ApiReferenceLayout.vue.js +1 -1
package/dist/components/ApiReferenceLayout.vue2.js +156 -138
package/dist/components/Content/Operation/PathResponses/ExampleResponse.vue.d.ts.map +1 -1
package/dist/components/Content/Operation/PathResponses/ExampleResponse.vue.js +2 -2
package/dist/components/Content/Operation/PathResponses/ExampleResponse.vue2.js +55 -44
package/dist/components/MobileHeader.vue.d.ts.map +1 -1
package/dist/components/MobileHeader.vue.js +3 -3
package/dist/components/Sidebar/Sidebar.vue.d.ts.map +1 -1
package/dist/components/Sidebar/Sidebar.vue.js +1 -1
package/dist/hooks/useReactiveSpec.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/style.css +1 -1
package/package.json +6 -6

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,34 @@
 # @scalar/api-reference
+## 1.24.17
+### Patch Changes
+- Updated dependencies [c20c7d0]
+- Updated dependencies [c20c7d0]
+  - @scalar/components@0.12.1
+  - @scalar/oas-utils@0.2.4
+  - @scalar/api-client@1.3.16
+  - @scalar/api-client-modal@0.0.13
+## 1.24.16
+### Patch Changes
+- 716811f: fix: HTML API does not work with YAML content inside script tag
+- 5812c2f: feat: allow custom headers
+- ee5fdee: fix: api reference allof items merge objects
+- Updated dependencies [e4419ce]
+- Updated dependencies [e5ac3e1]
+- Updated dependencies [f2c1019]
+- Updated dependencies [fd0c93d]
+- Updated dependencies [7b87b8c]
+- Updated dependencies [512c815]
+  - @scalar/components@0.12.0
+  - @scalar/use-tooltip@1.0.0
+  - @scalar/api-client@1.3.15
+  - @scalar/api-client-modal@0.0.12
 ## 1.24.15
 ### Patch Changes

package/README.md CHANGED Viewed

@@ -29,284 +29,119 @@ import '@scalar/api-reference/style.css'
 </template>
 ```
-You can even [mount the component in React](https://github.com/scalar/scalar/blob/main/examples/react/src/App.tsx).
-## OpenAPI Specification
-We’re expecting the passed specification to adhere to [the Swagger 2.0, OpenAPI 3.0 or OpenAPI 3.1 specification](https://github.com/OAI/OpenAPI-Specification).
-On top of that, we’ve added a few things for your convenience:
-### x-displayName
-You can overwrite tag names with `x-displayName`.
-```diff
-openapi: 3.1.0
-info:
-  title: Example
-  version: "1.0"
-tags:
-  - name: pl4n3t5
-+    x-displayName: planets
-paths:
-  '/planets':
-    get:
-      summary: Get all planets
-      tags:
-        - pl4n3t5
-```
-### x-tagGroup
-You can group your tags with `x-tagGroup`.
-```diff
-openapi: 3.1.0
-info:
-  title: Example
-  version: "1.0"
-tags:
-  - name: planets
-+x-tagGroups:
-+  - name: galaxy
-+    tags:
-+      - planets
-paths:
-  '/planets':
-    get:
-      summary: Get all planets
-      tags:
-        - planets
-```
-### x-internal
-You can hide operations from the reference with `x-internal`.
-```diff
-openapi: 3.1.0
-info:
-  title: Example
-  version: "1.0"
-paths:
-  '/planets':
-    get:
-      summary: Get all planets
-    post:
-      summary: Create a new planet
-+      x-internal: true
-```
-## Configuration
-There’s a configuration object that can be used on all platforms. In Vue.js, you use it like this:
-#### isEditable?: boolean
-Whether the Swagger editor should be shown.
-```vue
-<ApiReference :configuration="{ isEditable: true }" />
-```
-#### spec.content?: string
-Directly pass an OpenAPI/Swagger spec.
+### CDN
+```html
+<!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>
+    <!-- Add your own OpenAPI/Swagger specification URL here: -->
+    <!-- Note: The example is our public proxy (to avoid CORS issues). You can remove the `data-proxy-url` attribute if you don’t need it. -->
+    <script
+      id="api-reference"
+      data-url="https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml"
+      data-proxy-url="https://proxy.scalar.com"></script>
+    <!-- Optional: You can set a full configuration object like this: -->
+    <script>
+      var configuration = {
+        theme: 'purple',
+      }
-```vue
-<ApiReference :configuration="{ spec: { content: '{ … }' } }" />
+      document.getElementById('api-reference').dataset.configuration =
+        JSON.stringify(configuration)
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>
 ```
-#### spec.url?: string
+You can also use the following syntax to directly pass an OpenAPI specification:
-Pass the URL of a spec file (JSON or Yaml).
-```vue
-<ApiReference :configuration="{ spec: { url: '/openapi.json' } }" />
+```html
+<script
+  id="api-reference"
+  type="application/json">
+  { … }
+</script>
 ```
-#### proxyUrl?: string
+If you’d like to add a request proxy for the API client (to avoid CORS issues):
-Making requests to other domains is restricted in the browser and requires [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). It’s recommended to use a proxy to send requests to other origins.
-```vue
-<ApiReference :configuration="{ proxy: 'https://proxy.example.com' }" />
+```html
+<script
+  id="api-reference"
+  type="application/json"
+  data-proxy-url="https://proxy.scalar.com">
+  { … }
+</script>
 ```
-You can use our hosted proxy:
+#### Events [beta]
-```vue
-<ApiReference :configuration="{ proxy: 'https://proxy.scalar.com' }" />
-```
-If you like to run your own, check out our [example proxy written in Go](https://github.com/scalar/scalar/tree/main/examples/proxy-server).
+We have recently added two events to the standalone CDN build only.
-#### showSidebar?: boolean
+##### scalar:reload-references
-Whether the sidebar should be shown.
+Reload the references, this will re-mount the app in case you have switched pages or the dom
+elements have been removed.
-```vue
-<ApiReference :configuration="{ showSidebar: true } />
+```ts
+document.dispatchEvent(new Event('scalar:reload-references'))
 ```
-#### hideModels?: boolean
+##### scalar:update-references-config
-Whether models (`components.schemas` or `definitions`) should be shown in the sidebar, search and content.
+If you have updated the config or spec, you can trigger this event with the new payload to update
+the app. It should update reactively so you do not need to trigger the reload event above after.
-`@default false`
+```ts
+import { type ReferenceProps } from './types'
-```vue
-<ApiReference :configuration="{ hideModels: true } />
+const ev = new CustomEvent('scalar:update-references-config', {
+  detail: {
+    configuration: {
+      spec: {
+        url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
+      },
+    },
+  } satisfies ReferenceProps,
+})
+document.dispatchEvent(ev)
 ```
-#### hideDownloadButton?: boolean
+## Vue.js
-Whether to show the "Download OpenAPI Specification" button
+The API Reference is built in Vue.js. If you’re working in Vue.js, too, you can directly use our Vue components.
+Install them via `npm`:
-`@default false`
-```vue
-<ApiReference :configuration="{ hideDownloadButton: true } />
+```bash
+npm install @scalar/api-reference
 ```
-### customCss?: string
-You can pass custom CSS directly to the component. This is helpful for the integrations for Fastify, Express, Hono and others where you it’s easier to add CSS to the configuration.
-In Vue or React you’d probably use other ways to add custom CSS.
+And import the `ApiReference` component and style to your app:
 ```vue
-<script setup>
-const customCss = `* { font-family: "Comic Sans MS", cursive, sans-serif; }`
+<script setup lang="ts">
+import { ApiReference } from '@scalar/api-reference'
+import '@scalar/api-reference/style.css'
 </script>
 <template>
-  <ApiReference :configuration="{ customCss }" />
-</template>
-```
-#### searchHotKey?: string
-Key used with CTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k)
-```vue
-<ApiReference :configuration="{ searchHotKey: 'l'} />
-```
-#### servers?: Server[]
-List of servers to override the openapi spec servers
-@default undefined
-@example [{ url: 'https://api.scalar.com', description: 'Production server' }]
-```vue
-<ApiReference :configuration="{ servers: [{ url: 'https://api.scalar.com', description: 'Production server' }] } />
-```
-#### metaData?: object
-You can pass information to the config object to configure meta information out of the box.
-```vue
-<ApiReference :configuration="{
-  metaData: {
-        title: 'Page title',
-        description: 'My page page',
-        ogDescription: 'Still about my my page',
-        ogTitle: 'Page title',
-        ogImage: 'https://example.com/image.png',
-        twitterCard: 'summary_large_image',
-        //Add more...
-      }
-  } />
-```
-#### hiddenClients?: array | true
-You can pass an array of [httpsnippet clients](https://github.com/Kong/httpsnippet/wiki/Targets) to hide from the clients menu.
-```vue
-<ApiReference :configuration="{
-  hiddenClients: ['fetch']
-  } />
-```
-By default hides Unirest, pass `[]` to **show** all clients or `true` to **hide** all clients:
-```vue
-<ApiReference :configuration="{
-  hiddenClients: true
-  } />
-```
-#### onSpecUpdate?: (spec: string) => void
-You can listen to spec changes with onSpecUpdate that runs on spec/swagger content change
-```vue
-<ApiReference :configuration="{
-    onSpecUpdate: (value: string) => {
-      console.log('Content updated:', value)
-    }
-  } />
-```
-#### authentication?: Partial<AuthenticationState>
-To make authentication easier you can prefill the credentials for your users:
-```vue
-<ApiReference :configuration="{
-  authentication: {
-      // The OpenAPI file has keys for all security schemes:
-      // Which one should be used by default?
-      preferredSecurityScheme: 'my_custom_security_scheme',
-      // The `my_custom_security_scheme` security scheme is of type `apiKey`, so prefill the token:
-      apiKey: {
-        token: 'super-secret-token',
-      },
-    },
-  } />
-```
-For OpenAuth2 it’s more looking like this:
-```vue
-<ApiReference :configuration="{
-  authentication: {
-      // The OpenAPI file has keys for all security schemes
-      // Which one should be used by default?
-      preferredSecurityScheme: 'oauth2',
-      // The `oauth2` security scheme is of type `oAuth2`, so prefill the client id and the scopes:
-      oAuth2: {
-        clientId: 'foobar123',
-        // optional:
-        scopes: ['read:planets', 'write:planets'],
+  <ApiReference
+    :configuration="{
+      spec: {
+        url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
       },
-    },
-  } />
-```
-#### withDefaultFonts?: boolean
-By default we’re using Inter and JetBrains Mono, served by Google Fonts. If you use a different font or just don’t want to use Google Fonts, pass `withDefaultFonts: false` to the configuration.
-```vue
-<ApiReference :configuration="{
-  withDefaultFonts: false
-} />
+    }" />
+</template>
 ```
-#### theme?: string
-You don’t like the color scheme? We’ve prepared some themes for you:
-Can be one of: **alternate**, **default**, **moon**, **purple**, **solarized**, **bluePlanet**, **saturn**, **kepler**, **mars**, **deepSpace**, **none**
-```vue
-<ApiReference :configuration="{
-  theme: default
-} />
-```
+You can [pass props to customize the API reference](https://github.com/scalar/scalar/tree/main/documentation/configuration.md).