docs: update AsyncAPI example to v3 syntax in Python tutorial#1822
docs: update AsyncAPI example to v3 syntax in Python tutorial#1822payal723 wants to merge 1 commit intoasyncapi:masterfrom
Conversation
payal723
requested review from
Florence-Njeri,
asyncapi-bot-eve and
derberg
as code owners
|
📝 WalkthroughWalkthroughUpdates the AsyncAPI sample document in generator-template.md from version 2.6.0 to 3.0.0, restructuring channel definitions, server configuration (url to host), and introducing new components for schemas and operations to align with AsyncAPI 3.x semantics. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (4)📓 Common learnings📚 Learning: 2025-05-12T14:23:48.919ZApplied to files:
📚 Learning: 2025-05-12T14:23:48.919ZApplied to files:
📚 Learning: 2026-01-05T09:57:34.800ZApplied to files:
🔇 Additional comments (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
What reviewer looks at during PR reviewThe following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.
|
|
|
🚀 Docs preview deployed |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
apps/generator/docs/generator-template.md (3)
602-628: Update AsyncAPI example in section 5d to v3 syntax.Section "5d. Update AsyncAPI document" (lines 602-628) still uses AsyncAPI v2 syntax with
publishoperations nested directly under channels:channels: temperature/dropped: publish: operationId: temperatureDropThis contradicts the v3 example shown earlier (lines 60-75), which uses separate
channelswithaddressand top-leveloperationssections. To avoid confusing users, this section should be updated to v3 syntax to match the earlier migration.🔄 Proposed v3 update for section 5d
Update the example to use v3 structure:
channels: temperatureDroppedChannel: address: temperature/dropped description: Notifies the user when the temperature drops past a certain point. messages: temperatureDropMessage: description: Message that is being sent when the temperature drops past a certain point. payload: $ref: '#/components/schemas/temperatureId' temperatureRisenChannel: address: temperature/risen description: Notifies the user when the temperature rises past a certain point. messages: temperatureRisenMessage: description: Message that is being sent when the temperature rises past a certain point. payload: $ref: '#/components/schemas/temperatureId' operations: temperatureDrop: action: receive channel: $ref: '#/channels/temperatureDroppedChannel' messages: - $ref: '#/channels/temperatureDroppedChannel/messages/temperatureDropMessage' temperatureRise: action: receive channel: $ref: '#/channels/temperatureRisenChannel' messages: - $ref: '#/channels/temperatureRisenChannel/messages/temperatureRisenMessage'Based on learnings, this inconsistency should be addressed before merging, as leaving the v2 syntax later in the tutorial defeats the purpose of the migration and will create confusion for users following the tutorial.
526-540: Fix the channel-to-operations access pattern for AsyncAPI v3 compatibility.The
getTopicsfunction callsch.operations().filterByReceive()which is incompatible with AsyncAPI v3. In v3, operations are top-level decoupled entities that reference channels via$ref, not vice versa. The channel object does not expose an.operations()method.Correct the pattern to iterate operations at the document level and filter for those referencing the target channel:
const operationsForChannel = asyncapi.operations().all().filter(op => op.channel().id() === ch.id()); const receiveOp = operationsForChannel.find(op => op.action() === 'receive'); const operationId = receiveOp?.id();
399-399: Update server URL accessor for AsyncAPI v3 compatibility.The
.url()method does not exist in AsyncAPI v3 servers. The v3 Server Object was split into separatehost,pathname, andprotocolproperties. Update lines 399, 413, and 444 to useasyncapi.servers().get(params.server).host()and.pathname()instead of.url(), or construct the full URL from these components as needed.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
apps/generator/docs/generator-template.md
🧰 Additional context used
🧠 Learnings (4)
📓 Common learnings
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe
3. Messages are defined under a 'messages' container in channels
4. Servers can use a 'host' property
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with action property (send/receive) and references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe operations
3. Messages are defined under a 'messages' container in channels
4. The specification decouples operations, channels and messages to improve reusability
5. Servers can use a 'host' property
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Update relevant Generator documentation to accurately reflect PR changes introduced
Learnt from: derberg
Repo: asyncapi/generator PR: 1536
File: packages/templates/clients/websocket/test/__fixtures__/asyncapi-slack-client.yml:48-53
Timestamp: 2025-05-06T12:39:42.189Z
Learning: In AsyncAPI 3.0.0, security schemes can be defined inline directly at various levels including the server level, and don't need to be centrally defined in components.securitySchemes first. This is a change from previous versions of the AsyncAPI specification.
Learnt from: derberg
Repo: asyncapi/generator PR: 1536
File: packages/templates/clients/websocket/test/__fixtures__/asyncapi-slack-client.yml:48-53
Timestamp: 2025-05-06T12:39:42.189Z
Learning: In AsyncAPI 3.0, security schemes can be defined inline directly at the server level (and other levels) and don't need to be centrally defined in components.securitySchemes first. This is a change from previous versions of the AsyncAPI specification. The PR's approach with inline security definition is valid:
```yaml
security:
- type: http
scheme: bearer
bearerFormat: OAuth2
description: |
First you need to obtain a token...
```
📚 Learning: 2025-05-12T14:23:48.919Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe
3. Messages are defined under a 'messages' container in channels
4. Servers can use a 'host' property
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-05-12T14:23:48.919Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with action property (send/receive) and references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe operations
3. Messages are defined under a 'messages' container in channels
4. The specification decouples operations, channels and messages to improve reusability
5. Servers can use a 'host' property
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:34.800Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Update relevant Generator documentation to accurately reflect PR changes introduced
Applied to files:
apps/generator/docs/generator-template.md
🔇 Additional comments (1)
apps/generator/docs/generator-template.md (1)
45-85: AsyncAPI v3.0.0 example structure is correct.The example follows the AsyncAPI 3.0.0 specification correctly:
- Server uses
hostproperty for the broker address- Channel defines
addressfor the topic path- Messages are properly organized in a messages container within the channel
- Operations are top-level with
action: receive, channel reference, and message references that correctly point to the channel's messagesExample validates against the v3.0.0 specification.
3 participants
I've updated the AsyncAPI example used in the Python MQTT tutorial to use version 3 syntax. Earlier it was using v2.6.0, so I migrated the structure to match v3 updated channels, operations, and message definitions accordingly.
I kept the changes minimal and only focused on the YAML file for now. No template or parser logic was touched.
Also validated the file locally using asyncapi validate and it checks out.
This is just the first small step toward fully updating the tutorial to v3. Let me know if anything needs tweaking!
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.