Asyncapi Mqtt
title: "AsyncAPI with MQTT" description: "Learn how to document MQTT brokers, topics, QoS levels, and IoT device communication using AsyncAPI specifications and bindings." weight: 27 date: 2026-06-28 lastmod: 2026-06-28 tags: ["apis", "asyncapi"]
MQTT is a lightweight messaging protocol widely used in IoT and mobile applications. AsyncAPI provides bindings for documenting MQTT brokers, topics, QoS levels, and device-specific configurations.
## What You'll Learn
- MQTT server configuration in AsyncAPI
- Topic hierarchy and wildcards
- QoS level documentation
- Last will and testament configuration
- MQTT 5.0 features
## Why It Matters
MQTT deployments involve many devices with specific QoS and security requirements. AsyncAPI documentation ensures consistent configuration across all devices and enables automated provisioning.
## Real-World Use
A smart agriculture company deploys thousands of sensors across farms. Each sensor type has an AsyncAPI spec documenting its MQTT topics, QoS levels, and data formats. New sensors are configured automatically from the spec.
## Flow Chart
```mermaid
flowchart LR
A[MQTT AsyncAPI] --> B[Broker Config]
A --> C[Topic Structure]
A --> D[QoS Settings]
B --> E[Keep Alive]
B --> F[Last Will]
C --> G[Wildcards]
D --> H[QoS 0/1/2]
H --> I[Delivery Guarantee]
Code Examples
Example 1: MQTT Server with Last Will
asyncapi: '2.6.0'
info:
title: IoT Sensor Network
version: '1.0.0'
servers:
mqtt-production:
url: mqtt://iot.example.com:1883
protocol: mqtt
protocolVersion: '3.1.1'
description: Production MQTT broker
bindings:
mqtt:
clientId: sensor-gateway-prod
cleanSession: true
keepAlive: 60
sessionExpiryInterval: 3600
maximumPacketSize: 4096
lastWill:
topic: gateway/status
qos: 1
retain: true
message: '{"status": "offline"}'
mqtt-secure:
url: mqtts://iot-secure.example.com:8883
protocol: mqtts
protocolVersion: '3.1.1'
bindings:
mqtt:
clientId: sensor-gateway-secure
cleanSession: false
keepAlive: 120
Expected output: MQTT server configurations with last will, keep-alive, and session settings for both standard and secure connections.
Example 2: MQTT Topics with QoS
channels:
sensor/{deviceId}/temperature:
parameters:
deviceId:
schema:
type: string
pattern: '^sensor-[a-f0-9]{8}$'
description: Temperature readings from IoT sensors
bindings:
mqtt:
qos: 1
retain: false
messageExpiryInterval: 300
publish:
operationId: emitTemperature
summary: Publish temperature reading
message:
contentType: application/json
bindings:
mqtt:
payloadFormatIndicator: 1
contentType: application/json
payload:
type: object
properties:
temperature:
type: number
unit:
type: string
enum: [celsius, fahrenheit]
timestamp:
type: string
format: date-time
sensor/{deviceId}/humidity:
bindings:
mqtt:
qos: 0
retain: false
publish:
message:
payload:
type: object
properties:
humidity:
type: number
timestamp:
type: string
format: date-time
sensor/{deviceId}/alerts:
bindings:
mqtt:
qos: 2
retain: true
publish:
message:
payload:
type: object
properties:
alertType:
type: string
severity:
type: string
enum: [low, medium, high, critical]
Expected output: Different MQTT topics with different QoS levels based on data criticality (QoS 0 for humidity, QoS 1 for temperature, QoS 2 for alerts).
Example 3: MQTT 5.0 Features
asyncapi: '2.6.0'
info:
title: MQTT 5.0 Advanced Features
version: '1.0.0'
servers:
broker:
url: mqtt://broker.example.com:1883
protocol: mqtt
protocolVersion: '5.0'
bindings:
mqtt:
sessionExpiryInterval: 86400
receiveMaximum: 1000
maximumPacketSize: 65535
topicAliasMaximum: 100
maximumQoS: 2
retainAvailable: true
wildcardSubscriptionAvailable: true
subscriptionIdentifierAvailable: true
sharedSubscriptionAvailable: true
channels:
command/{deviceId}:
bindings:
mqtt:
qos: 1
retain: false
subscribe:
operationId: receiveCommand
bindings:
mqtt:
subscriptionIdentifier: 42
subscriptionOptions:
noLocal: true
retainAsPublished: false
retainHandling: 0
message:
bindings:
mqtt:
contentType: application/cbor
payloadFormatIndicator: 0
responseTopic: response/{deviceId}
correlationData:
type: string
format: byte
userProperties:
- name: command-version
value: '1.0'
- name: source
value: cloud-service
Expected output: MQTT 5.0 features including session expiry, receive maximum, subscription options, response topics, and user properties.
Common Mistakes
| Mistake | Explanation |
|---|---|
| Using wrong QoS for critical data | Critical alerts should use QoS 2; telemetry can use QoS 0 or 1 |
| Forgetting retain flags | Retain important status messages (device status, last known values) |
| Ignoring last will | Every device should have a last will to signal unexpected disconnection |
| Not using topic hierarchies | Flat topic structures are hard to manage; use hierarchical topics with device IDs |
| Missing payload format indicators | Set payloadFormatIndicator to help consumers deserialize messages correctly |
Practice Questions
- What QoS level should you use for critical alerts?
- How do you configure a last will and testament in AsyncAPI MQTT bindings?
- What are MQTT topic wildcards and how do they relate to channel parameters?
- How do MQTT 5.0 features differ from 3.1.1 in AsyncAPI?
- How do you document a shared subscription in MQTT?
Challenge
Design an AsyncAPI specification for a fleet management system with MQTT communication. Include topics for GPS location (QoS 1), engine diagnostics (QoS 0), emergency alerts (QoS 2 with retain), and remote commands (MQTT 5.0 response topics).
FAQ
Mini Project
Design a complete MQTT-based smart building management system with AsyncAPI. Include topics for HVAC (temperature, humidity), lighting (status, commands), security (alerts, camera status), and access control (door locks, ID badges). Use appropriate QoS levels for each data type.
What's Next
Learn how to use AsyncAPI with WebSocket
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro