@scalar/hono-api-reference 0.12.12 → 0.12.14

package/dist/scalar.d.ts

@@ -3,23 +3,23 @@ import { Hono } from 'hono';
 import type { ApiReferenceConfiguration } from './types.js';
 type Configuration<E extends Env> = Partial<ApiReferenceConfiguration> | ((c: Context<E>) => Partial<ApiReferenceConfiguration> | Promise<Partial<ApiReferenceConfiguration>>);
 /**
- * An OpenAPI document.
+ * An OpenAPI or AsyncAPI document.
  *
  * Typed loosely as an object on purpose, so it accepts both plain document objects and the typed
  * return values of generators like Zod OpenAPI Hono's `getOpenAPI31Document()`, whose interfaces do
  * not carry an index signature.
  */
-type OpenApiDocument = object;
+type ApiDocument = object;
 /**
  * The configuration for `Scalar.serve`.
  *
- * On top of the universal API Reference configuration, this takes the OpenAPI `document` to render
+ * On top of the universal API Reference configuration, this takes the API `document` to render
  * and expose. Because `Scalar.serve` sources the document itself, `content` and `url` are managed for
  * you and are not accepted here.
  */
 export type ServeConfiguration<E extends Env> = Omit<Partial<ApiReferenceConfiguration>, 'content' | 'url'> & {
     /**
-     * The OpenAPI document to render and serve.
+     * The OpenAPI or AsyncAPI document to render and serve.
      *
      * Pass the document directly, or a function that returns it. The function receives the Hono
      * `Context`, so it can read `c.env` or `c.req` and build the document per request. This is also how
@@ -32,9 +32,11 @@ export type ServeConfiguration<E extends Env> = Omit<Partial<ApiReferenceConfigu
      * }))
      * ```
      */
-    document: OpenApiDocument | ((c: Context<E>) => OpenApiDocument | Promise<OpenApiDocument>);
+    document: ApiDocument | ((c: Context<E>) => ApiDocument | Promise<ApiDocument>);
     /**
-     * Path, relative to the mount point, where the OpenAPI document is served as JSON.
+     * Path, relative to the mount point, where the API document is served as JSON.
+     *
+     * Use `/asyncapi.json` for an AsyncAPI document. The default stays `/openapi.json` for either format.
      *
      * @default '/openapi.json'
      */
@@ -44,7 +46,7 @@ export type ServeConfiguration<E extends Env> = Omit<Partial<ApiReferenceConfigu
  * Render the Scalar API Reference in a Hono app.
  *
  * Use `Scalar(...)` as a middleware to render the reference on a route, or `Scalar.serve(...)` to
- * serve the reference and its OpenAPI document together from a single mount.
+ * serve the reference and its OpenAPI or AsyncAPI document together from a single mount.
  */
 export declare const Scalar: (<E extends Env>(configOrResolver: Configuration<E>) => MiddlewareHandler<E>) & {
     serve: <E extends Env>(options: ServeConfiguration<E>) => Hono<E>;

package/dist/scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AA+DxD,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAC5B,OAAO,CAAC,yBAAyB,CAAC,GAClC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAA;AA2BzG;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,MAAM,CAAA;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG;IAC5G;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAA;IAC3F;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAgDD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,IAlHO,CAAC,SAAS,GAAG,oBAAoB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAAC;YA+E7E,CAAC,SAAS,GAAG,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,CAAC,CAAC;CAmCC,CAAA"}
+{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AA+DxD,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAC5B,OAAO,CAAC,yBAAyB,CAAC,GAClC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAA;AA2BzG;;;;;;GAMG;AACH,KAAK,WAAW,GAAG,MAAM,CAAA;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG;IAC5G;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAA;IAC/E;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAkDD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,IAtHO,CAAC,SAAS,GAAG,oBAAoB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAAC;YAmF7E,CAAC,SAAS,GAAG,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,CAAC,CAAC;CAmCC,CAAA"}

package/dist/scalar.js

@@ -82,12 +82,14 @@ const scalarMiddleware = (configOrResolver) => {
     };
 };
 /**
- * Serve the API Reference and its OpenAPI document together as a mountable Hono app.
+ * Serve the API Reference and its OpenAPI or AsyncAPI document together as a mountable Hono app.
  *
  * Unlike the `Scalar` middleware — which only renders the reference and expects the document to live
  * somewhere else — this exposes both from a single call, so you do not have to wire up a separate
  * document route and keep its `url` in sync.
  *
+ * This serves an existing document or calls your factory; it does not generate a document from routes.
+ *
  * Mount it with `app.route(...)`:
  *
  * @example
@@ -95,14 +97,14 @@ const scalarMiddleware = (configOrResolver) => {
  * import { Scalar } from '@scalar/hono-api-reference'
  *
  * // Serves the reference at `/scalar` and the document at `/scalar/openapi.json`
- * app.route('/scalar', Scalar.serve({ document: myOpenApiDocument }))
+ * app.route('/scalar', Scalar.serve({ document: myApiDocument }))
  * ```
  */
 const scalarServe = (options) => {
     const { document, documentPath = '/openapi.json', ...rest } = options;
     const app = new Hono();
     const resolveDocument = (c) => typeof document === 'function' ? document(c) : document;
-    // Expose the OpenAPI document as JSON, so a single call powers both the reference and its source.
+    // Expose the API document as JSON, so a single call powers both the reference and its source.
     app.get(documentPath, async (c) => c.json(await resolveDocument(c)));
     // Render the reference, pointing it at the document we expose above.
     app.get('/', (c) => {
@@ -122,6 +124,6 @@ const scalarServe = (options) => {
  * Render the Scalar API Reference in a Hono app.
  *
  * Use `Scalar(...)` as a middleware to render the reference on a route, or `Scalar.serve(...)` to
- * serve the reference and its OpenAPI document together from a single mount.
+ * serve the reference and its OpenAPI or AsyncAPI document together from a single mount.
  */
 export const Scalar = Object.assign(scalarMiddleware, { serve: scalarServe });

package/dist/scalar.test.js

@@ -206,6 +206,65 @@ describe('Scalar', () => {
         expect(text).toContain('Test API');
         expect(text).toContain('deepSpace');
     });
+    it.each([
+        { mount: '/', source: 'object' },
+        { mount: '/api/reference', source: 'object' },
+        { mount: '/', source: 'factory' },
+        { mount: '/api/reference', source: 'factory' },
+        { mount: '/', source: 'async factory' },
+        { mount: '/api/reference', source: 'async factory' },
+    ])('serves an AsyncAPI $source mounted at $mount', async ({ mount, source }) => {
+        const document = {
+            asyncapi: '3.0.0',
+            info: { title: 'WebSocket Chat', version: '1.0.0' },
+            servers: {
+                local: { host: 'localhost:3000', protocol: 'ws' },
+            },
+            channels: {
+                chat: {
+                    address: '/chat',
+                    servers: [{ $ref: '#/servers/local' }],
+                    messages: {
+                        text: { payload: { type: 'string' } },
+                    },
+                },
+            },
+            operations: {
+                receiveMessage: {
+                    action: 'receive',
+                    channel: { $ref: '#/channels/chat' },
+                    messages: [{ $ref: '#/channels/chat/messages/text' }],
+                },
+            },
+        };
+        const documentUrl = mount === '/' ? '/asyncapi.json' : '/api/reference/asyncapi.json';
+        const app = new Hono();
+        const reference = Scalar.serve({
+            document: source === 'object'
+                ? document
+                : (c) => {
+                    expect(c.req.path).toBe(documentUrl);
+                    return source === 'async factory' ? Promise.resolve(document) : document;
+                },
+            documentPath: '/asyncapi.json',
+        });
+        if (mount === '/') {
+            app.route('/', reference);
+        }
+        else {
+            const api = new Hono();
+            api.route('/reference', reference);
+            app.route('/api', api);
+        }
+        const html = await app.request(mount);
+        expect(html.status).toBe(200);
+        expect(html.headers.get('content-type')).toContain('text/html');
+        expect(await html.text()).toContain(`"url": "${documentUrl}"`);
+        const json = await app.request(documentUrl);
+        expect(json.status).toBe(200);
+        expect(json.headers.get('content-type')).toContain('application/json');
+        expect(await json.json()).toStrictEqual(document);
+    });
     describe('serve', () => {
         const document = {
             openapi: '3.1.0',

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "integrations/hono"
   },
-  "version": "0.12.12",
+  "version": "0.12.14",
   "engines": {
     "node": ">=22"
   },
@@ -44,15 +44,15 @@
     "documentation": "https://scalar.com/products/api-references/integrations/hono"
   },
   "dependencies": {
-    "@scalar/client-side-rendering": "0.4.11"
+    "@scalar/client-side-rendering": "0.4.13"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.1.1",
+    "@hono/node-server": "^2.1.5",
     "@hono/zod-openapi": "^1.6.3",
-    "@scalar/openapi-to-markdown": "1.5.4",
-    "hono": "^4.13.8",
-    "vite": "8.1.5",
-    "vitest": "4.1.10"
+    "@scalar/openapi-to-markdown": "1.7.0",
+    "hono": "^4.13.13",
+    "vite": "8.3.4",
+    "vitest": "4.1.12"
   },
   "peerDependencies": {
     "hono": "^4.12.5"