feat(asyncapi): add AsyncAPI documentation generator and HTTP plugin

- Introduced `@mqttkit/asyncapi` package for generating AsyncAPI 3.0 documentation.
- Implemented core functionality to build AsyncAPI documents from MQTT routes.
- Added support for serving JSON, YAML, and HTML documentation over HTTP.
- Created example integration with Elysia and Aedes for MQTT-over-WS.
- Updated tests to cover new publish policies and middleware behavior.
- Included license and README files for the new package.

Author: keyp-dev

README.md

@@ -15,6 +15,7 @@ mqttkit does not reimplement the MQTT protocol. A broker such as Aedes owns CONN
 - `app.on()` observes broker lifecycle events such as client, publish, subscribe, ack, and errors.
 - `app.publish()` lets services, workers, and consumers push messages to MQTT clients through the broker.
 - `@mqttkit/aedes` provides TCP MQTT and MQTT-over-WebSocket support through Aedes.
+- `@mqttkit/asyncapi` generates AsyncAPI 3.0 documentation from routes and serves a browsable docs page.
 - Built for Bun and TypeScript.
 
 ## Installation
@@ -279,6 +280,8 @@ Use Aedes persistence adapters for offline queues, retain, QoS sessions, and dur
 - `examples/events`: broker lifecycle events.
 - `examples/service-push`: external service calls `app.publish()`, then Aedes delivers to subscribed MQTT clients.
 - `examples/kafka-bridge`: MQTT messages go to Kafka, and Kafka consumer messages are forwarded to MQTT clients.
+- `examples/asyncapi-docs`: AsyncAPI documentation served from `@mqttkit/asyncapi` (standalone HTTP).
+- `examples/asyncapi-elysia`: share a single Elysia port for both AsyncAPI docs and MQTT-over-WebSocket (aedes ws attached to the same `http.Server`).
 
 Run an example:
 
@@ -307,3 +310,4 @@ bun run build
 
 - `@mqttkit/core`: core application, router, middleware, context, event types, and broker adapter interface.
 - `@mqttkit/aedes`: Aedes adapter for TCP MQTT and MQTT-over-WebSocket.
+- `@mqttkit/asyncapi`: AsyncAPI 3.0 generator and HTTP plugin for browsable docs.

README.zh-CN.md

@@ -15,6 +15,7 @@ mqttkit 不重新实现 MQTT 协议。CONNECT、SUBSCRIBE、PUBLISH、QoS、reta
 - `app.on()` 监听 client、publish、subscribe、ack、错误等 broker lifecycle events。
 - `app.publish()` 让外部服务、worker、consumer 通过 broker 主动推送消息给 MQTT client。
 - `@mqttkit/aedes` 基于 Aedes 提供 TCP MQTT 与 MQTT-over-WebSocket。
+- `@mqttkit/asyncapi` 从路由生成 AsyncAPI 3.0 文档，并通过 HTTP 提供可浏览的文档页面。
 - 面向 Bun 与 TypeScript。
 
 ## 安装
@@ -279,6 +280,8 @@ new MqttApp()
 - `examples/events`：监听 broker lifecycle events。
 - `examples/service-push`：外部服务调用 `app.publish()`，消息经 Aedes 投递到订阅中的 MQTT client。
 - `examples/kafka-bridge`：MQTT 消息写入 Kafka，并把 Kafka consumer 消息透传给 MQTT client。
+- `examples/asyncapi-docs`：通过 `@mqttkit/asyncapi` 提供 AsyncAPI 文档与浏览页面（独立 HTTP 端口）。
+- `examples/asyncapi-elysia`：Elysia 端口同时承载 AsyncAPI 文档与 MQTT-over-WebSocket（aedes ws 复用同一个 `http.Server`）。
 
 运行示例：
 
@@ -307,3 +310,4 @@ bun run build
 
 - `@mqttkit/core`：core application、router、middleware、context、event types 与 broker adapter 接口。
 - `@mqttkit/aedes`：Aedes adapter，提供 TCP MQTT 与 MQTT-over-WebSocket 接入。
+- `@mqttkit/asyncapi`：基于路由生成 AsyncAPI 3.0 文档与 HTTP 浏览页面。

bun.lock

@@ -0,0 +1,14 @@
+{
+  "name": "@mqttkit/example-asyncapi-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mqttkit/aedes": "workspace:*",
+    "@mqttkit/asyncapi": "workspace:*",
+    "@mqttkit/core": "workspace:*"
+  }
+}

examples/asyncapi-docs/package.json

@@ -0,0 +1,90 @@
+import { aedes } from '@mqttkit/aedes'
+import { asyncapi } from '@mqttkit/asyncapi'
+import { MqttApp, router } from '@mqttkit/core'
+
+type Principal = { uid: string }
+type State = { principal?: Principal }
+
+const deviceEventSchema = {
+  type: 'object',
+  required: ['temperature'],
+  properties: {
+    temperature: { type: 'number', description: 'Celsius reading' },
+    humidity: { type: 'number' },
+    ts: { type: 'integer', description: 'Unix ms' },
+  },
+}
+
+const notificationSchema = {
+  type: 'object',
+  required: ['kind', 'body'],
+  properties: {
+    kind: { type: 'string', enum: ['invoice', 'system', 'chat'] },
+    body: { type: 'string' },
+  },
+}
+
+const app = new MqttApp<State>()
+  .use(
+    aedes({
+      tcp: { port: 1883 },
+      authenticate: ({ username }) => {
+        if (!username) return false
+        return { uid: username }
+      },
+    }),
+  )
+  .use(
+    router<State>()
+      .topic('devices/:uid/events', {
+        publish: ({ params, principal }) => params.uid === principal?.uid,
+        qos: 1,
+        schema: deviceEventSchema,
+        async onMessage(ctx) {
+          await ctx.publish(`server/${ctx.params.uid}/echo`, ctx.payload, { qos: 0 })
+        },
+        meta: {
+          summary: 'Device telemetry uplink',
+          description: 'Device pushes sensor readings. Only the owning principal may publish.',
+          tags: ['device', 'telemetry'],
+          examples: [{ temperature: 22.5, humidity: 60, ts: Date.now() }],
+        },
+      })
+      .topic('server/:uid/echo', {
+        subscribe: ({ params, principal }) => params.uid === principal?.uid,
+        qos: 0,
+        meta: {
+          summary: 'Server echo channel',
+          description: 'Server echoes device events back to the owning client.',
+          tags: ['device'],
+        },
+      })
+      .topic('users/:uid/notifications', {
+        subscribe: ({ params, principal }) => params.uid === principal?.uid,
+        publish: false,
+        qos: 1,
+        retain: true,
+        schema: notificationSchema,
+        meta: {
+          summary: 'User notifications',
+          description: 'Server-pushed notifications. Clients subscribe only.',
+          tags: ['notifications'],
+        },
+      }),
+  )
+  .use(
+    asyncapi({
+      info: {
+        title: 'mqttkit demo',
+        version: '0.0.1',
+        description: 'AsyncAPI generated from mqttkit router metadata.',
+      },
+      servers: {
+        tcp: { host: 'localhost:1883', protocol: 'mqtt', description: 'Aedes TCP broker' },
+      },
+      port: 9000,
+    }),
+  )
+
+await app.listen()
+console.log('mqtt://localhost:1883 | docs: http://localhost:9000/docs')

examples/asyncapi-docs/src/index.ts

@@ -0,0 +1,17 @@
+{
+  "name": "@mqttkit/example-asyncapi-elysia",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mqttkit/aedes": "workspace:*",
+    "@mqttkit/asyncapi": "workspace:*",
+    "@mqttkit/core": "workspace:*",
+    "aedes": "^0.51.3",
+    "elysia": "^1.4.29",
+    "mqtt": "^5.15.1"
+  }
+}