docs: rewrite generator template tutorial to AsyncAPI v3#1826
docs: rewrite generator template tutorial to AsyncAPI v3#1826asyncapi-bot merged 11 commits intoasyncapi:masterfrom
Conversation
Harsh16gupta
requested review from
Florence-Njeri,
asyncapi-bot-eve and
derberg
as code owners
|
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.
|
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughUpdate templates, docs, and generator metadata to AsyncAPI v3 (2.6.0 → 3.0.1): server lookups use Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @apps/generator/docs/generator-template.md:
- Line 494: The TopicFunction component expects a prop named "operations"
(destructured as { operations }) but the invocations pass a "channels" prop;
update the two invocations that call TopicFunction (currently using
channels={asyncapi.operations().filterByReceive()}) to use
operations={asyncapi.operations().filterByReceive()} so the component receives
the correct prop name and avoids undefined operations at runtime.
📜 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 (7)
📓 Common learnings
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: 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
📚 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
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Run tests locally using npm run generator:test:unit for unit tests and npm run generator:test:integration for integration tests
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Applies to apps/generator/test/**/*.test.{js,ts} : Create new test files in the appropriate directory under apps/generator/test/ and follow existing test patterns
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-05-12T14:57:35.024Z
Learnt from: Adi-204
Repo: asyncapi/generator PR: 1557
File: packages/templates/clients/websocket/javascript/components/SendOperation.js:21-21
Timestamp: 2025-05-12T14:57:35.024Z
Learning: In the AsyncAPI generator templates, particularly in the JavaScript WebSocket client, single quotes are used for string literals inside template-generated code (which is itself inside backticks) to preserve template placeholders like ${variable} as literal text in the generated code output.
Applied to files:
apps/generator/docs/generator-template.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: preview
🔇 Additional comments (5)
apps/generator/docs/generator-template.md (5)
45-84: AsyncAPI v3.0.0 document examples are correct. The document properly reflects v3 structure with servers usinghost, channels withaddressand message containers, and top-level operations with channel references. Based on learnings, the migration correctly implements the v3 specification changes including operation-channel decoupling.
119-120: Generator configuration correctly updated for v3. TheapiVersionis set to "v3" and the generator version range ">=1.10.0 <=3.0.1" is appropriate for v3 compatibility.Also applies to: 333-334
398-398: Parser API usage is correct for AsyncAPI v3. All references use the correct v3 methods:asyncapi.servers().get(params.server).host()(instead of v2'surl()) andasyncapi.operations().filterByReceive()for operation filtering.Also applies to: 412-412, 443-443, 559-559
500-542: TopicFunction component correctly migrated to operations-based API. The component properly destructures theoperationsparameter, iterates through operations, and accesses their associated channels viaop.channels()to extract the address and operation ID. The logic correctly aligns with AsyncAPI v3 structure.
6-15: Tutorial narrative and objectives align with AsyncAPI v3 migration. The introduction, prerequisites, and learning objectives correctly set expectations for v3-based template development. The reference to the completed implementation in the author's repo supports reproducibility.
|
🚀 Docs preview deployed |
|
Verified with docker also 
|
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
apps/generator/docs/generator-template.md (1)
518-523: Clarify the getTopics function logic in documentation.The comment describes the output as "one for each channel" but the logic iterates over operations and extracts associated channel addresses. The explanation should reflect that the function processes operations and their channel references.
📝 Proposed comment improvement
/* - * This function returns a list of objects, one for each channel with two properties, name and topic - * name - holds information about the operationId provided in the AsyncAPI document - * topic - holds information about the address of the topic - * - * As input it requires a list of Channel models from the parsed AsyncAPI document + * This function returns a list of objects, one for each operation, with two properties: name and topic. + * name - holds the operationId from the AsyncAPI document (or generated ID if not set) + * topic - holds the address of the operation's associated channel + * + * As input it requires a list of Operation models from the parsed AsyncAPI document. */
🤖 Fix all issues with AI agents
In @apps/generator/docs/generator-template.md:
- Around line 501-504: The JSDoc incorrectly mentions "Channel models" but the
component now accepts an operations list; update the comment to say the input is
a list/array of operation objects (parameter name "operations") that map to
AsyncAPI v3 channel operations (e.g., each operation corresponds to a specific
channel and its publish/subscribe operation), and briefly explain that the
returned block provides helper functions to send messages to topics derived from
those operations; update any references to "channels" to clarify the
operations-to-channel relationship.
🧹 Nitpick comments (1)
apps/generator/docs/generator-template.md (1)
528-539: Silent skipping of operations without channels may mask configuration errors.The early return at line 530 skips operations that have no associated channels without any warning or logging. This could hide misconfigured AsyncAPI documents silently.
Consider logging a warning or including a note in documentation explaining that operations must have associated channels to be included in the generated output.
📜 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 (9)
📓 Common learnings
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: 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
📚 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
📚 Learning: 2025-05-06T12:39:42.189Z
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.
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-04-23T09:18:38.333Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1512
File: packages/templates/clients/websocket/javascript/components/AvailableOperations.js:10-15
Timestamp: 2025-04-23T09:18:38.333Z
Learning: In the asyncapi/generator repository, keys aren't required when mapping over operations array in the AvailableOperations component, contrary to the typical React pattern.
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Run tests locally using npm run generator:test:unit for unit tests and npm run generator:test:integration for integration tests
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Applies to apps/generator/test/**/*.test.{js,ts} : Create new test files in the appropriate directory under apps/generator/test/ and follow existing test patterns
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-05-12T14:57:35.024Z
Learnt from: Adi-204
Repo: asyncapi/generator PR: 1557
File: packages/templates/clients/websocket/javascript/components/SendOperation.js:21-21
Timestamp: 2025-05-12T14:57:35.024Z
Learning: In the AsyncAPI generator templates, particularly in the JavaScript WebSocket client, single quotes are used for string literals inside template-generated code (which is itself inside backticks) to preserve template placeholders like ${variable} as literal text in the generated code output.
Applied to files:
apps/generator/docs/generator-template.md
🔇 Additional comments (2)
apps/generator/docs/generator-template.md (2)
1-652: AsyncAPI v3 migration is comprehensive and well-documented.The tutorial successfully migrates from v2 to v3 with clear explanations of structural changes. The AsyncAPI document examples, generator configuration, and template code all reflect v3 patterns. The TopicFunction component correctly processes operations instead of channels, and examples demonstrate working implementations.
Based on learnings, the changes align with AsyncAPI v3 specification where operations become top-level elements with action property and channels use address fields.
398-398: All AsyncAPI v3 Parser API methods are available and correctly used.The methods
asyncapi.servers().get(params.server).host(),operations(),filterByReceive(),id(), andoperationId()are confirmed in the codebase. Thehost()method is actively used in helper functions (packages/helpers/src/servers.js), component code (packages/components/src/components/FileHeaderInfo.js), and test files, confirming the API pattern is valid and functional for v3 Parser.
|
@derberg whenever you have a moment, could you please have a look? |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
apps/generator/docs/generator-template.md (1)
505-542: Replaceop.operationId()withop.id()—the operationId method does not exist in Parser v3.The
TopicFunctioncomponent refactoring is otherwise correct. The methodsop.channels(),op.channels().all(),op.id(), andchannel.address()are all confirmed and working. However,op.operationId()is not a valid method in Parser v3.4.0. All working code in the repository uses onlyoperation.id().Change line 533 from:
const operationId = op.operationId() || op.id();to:
const operationId = op.id();
🤖 Fix all issues with AI agents
In @apps/generator/docs/generator-template.md:
- Around line 119-120: The generator version range in the template is incorrect:
update the "generator" field to use the documented range format by changing its
value from ">=1.10.0 <=3.0.1" to ">=1.3.0 <3.0.0" while keeping "apiVersion":
"v3" as-is; locate the "apiVersion" and "generator" entries in the template and
replace the generator string with the new lower bound >=1.3.0 and exclusive
upper bound <3.0.0.
📜 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 (9)
📓 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: 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: 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
📚 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
📚 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: Applies to **/*.{js,ts,jsx,tsx} : Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-04-23T09:18:38.333Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1512
File: packages/templates/clients/websocket/javascript/components/AvailableOperations.js:10-15
Timestamp: 2025-04-23T09:18:38.333Z
Learning: In the asyncapi/generator repository, keys aren't required when mapping over operations array in the AvailableOperations component, contrary to the typical React pattern.
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Run tests locally using npm run generator:test:unit for unit tests and npm run generator:test:integration for integration tests
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Applies to apps/generator/test/**/*.test.{js,ts} : Create new test files in the appropriate directory under apps/generator/test/ and follow existing test patterns
Applied to files:
apps/generator/docs/generator-template.md
📚 Learning: 2025-05-12T14:57:35.024Z
Learnt from: Adi-204
Repo: asyncapi/generator PR: 1557
File: packages/templates/clients/websocket/javascript/components/SendOperation.js:21-21
Timestamp: 2025-05-12T14:57:35.024Z
Learning: In the AsyncAPI generator templates, particularly in the JavaScript WebSocket client, single quotes are used for string literals inside template-generated code (which is itself inside backticks) to preserve template placeholders like ${variable} as literal text in the generated code output.
Applied to files:
apps/generator/docs/generator-template.md
🔇 Additional comments (4)
apps/generator/docs/generator-template.md (4)
47-84: LGTM! AsyncAPI v3 document structure is correct.The AsyncAPI document has been properly migrated to v3 with all the key structural changes in place: operations as top-level elements with
action: receive, channels usingaddressfor topic paths, messages under amessagescontainer, and servers using thehostproperty.Based on learnings, this aligns with AsyncAPI 3.0.0 specification requirements.
398-398: LGTM! Correct usage of host() for AsyncAPI v3.The template code has been correctly updated to use
asyncapi.servers().get(params.server).host()instead of the v2url()method. This change is consistently applied throughout all template examples.Based on learnings, servers in AsyncAPI v3 use the
hostproperty.Also applies to: 412-412, 443-443, 559-559
490-496: LGTM! Operations-based API correctly implemented for AsyncAPI v3.The template has been properly updated to use
asyncapi.operations().filterByReceive()instead of the v2 channel-based approach. This correctly reflects the v3 specification where operations are top-level elements with anactionproperty that can be filtered.The explanatory comment clearly describes that the template generates functions for operations marked with
action: receive.Based on learnings, AsyncAPI 3.0.0 decouples operations, channels, and messages to improve reusability.
Also applies to: 570-570
605-632: LGTM! Multi-channel AsyncAPI v3 document correctly structured.The updated AsyncAPI document with two channels (
temperatureDroppedandtemperatureRisen) and their corresponding operations (temperatureDropandtemperatureRise) is correctly structured for v3:
- Each channel uses the
addressfield for the topic path- Messages are properly nested under the
messagescontainer- Operations are defined at the top level with
action: receive- Operations reference channels using
$ref: '#/channels/...'This demonstrates the proper decoupling of operations, channels, and messages in AsyncAPI v3.
| "apiVersion": "v3", | ||
| "generator": ">=1.10.0 <=3.0.1", |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
AsyncAPI generator v3 API compatibility version requirements
💡 Result:
Short answer: Templates must declare apiVersion: "v3" in their generator configuration so the AsyncAPI Generator will use the Parser-API/Parser v3 runtime and accept AsyncAPI spec v3 documents. If a template omits or uses a non‑v3 apiVersion the Generator assumes older Parser-API behavior and will error (e.g., "Version '3.0.0' is not supported"). Also check the template's declared supported generator range (generator field) to ensure the template is compatible with your @asyncapi/generator version. [1][2][3]
Example (package.json or .ageneratorrc): include "apiVersion": "v3" under the generator config. [1][3]
Sources:
- AsyncAPI generator configuration documentation. [1]
- Generator version vs template version / compatibility checks. [2]
- Community example explaining setting apiVersion to "v3" to fix the error. [3]
🏁 Script executed:
# Search for AsyncAPI generator version information and v3 compatibility
rg -i "generator.*version|apiVersion.*v3|v3.*compatibility|changelog|release" --type=md --type=json -A 2 -B 2Repository: asyncapi/generator
Length of output: 37640
🏁 Script executed:
# Search for v3 API introduction in CHANGELOG
rg -A 5 -B 5 "v3.*API|Parser.*v3|apiVersion.*v3" apps/generator/CHANGELOG.md --type=md | head -100
# Look for generator version requirements and v3 compatibility mentions
rg "generator.*1\.\d+\.\d+|v3" apps/generator/docs/configuration-file.md -A 2 -B 2 --type=mdRepository: asyncapi/generator
Length of output: 4186
🏁 Script executed:
# Check if there's a specific release note about v3 support
rg -i "v3 parser|parser-api|apiVersion" apps/generator/CHANGELOG.md -C 5 --type=md | grep -A 10 -B 10 "v3"Repository: asyncapi/generator
Length of output: 708
🏁 Script executed:
# Search CHANGELOG more comprehensively for v3 support introduction
rg "v3|1\.3\.0|1\.10\.0" apps/generator/CHANGELOG.md -B 5 -A 5 | head -150Repository: asyncapi/generator
Length of output: 739
🏁 Script executed:
# Check the generator-template.md file specifically to see all version references
grep -n "generator.*1\." apps/generator/docs/generator-template.mdRepository: asyncapi/generator
Length of output: 147
🏁 Script executed:
# Search for when v3 API support was introduced in CHANGELOG
rg "Parser.*API.*v3|v3.*Parser|apiVersion.*v3" apps/generator/CHANGELOG.md -B 10 -A 10 | head -200Repository: asyncapi/generator
Length of output: 1210
🏁 Script executed:
# Look at actual package.json or configuration files in the repo to understand v3 requirements
fd "package.json" apps/generator/docs -o apps/generator/test | xargs grep -l "apiVersion" | head -5Repository: asyncapi/generator
Length of output: 219
🏁 Script executed:
# Check if there are any test templates or examples with v3 that show the actual minimum version needed
find apps/generator -name "*.json" -o -name "*.yaml" -o -name ".ageneratorrc" | xargs grep -h "apiVersion.*v3" -A 1 -B 1 2>/dev/null | sort | uniqRepository: asyncapi/generator
Length of output: 83
🏁 Script executed:
# Check the entire generator-template.md file context around those lines
sed -n '115,125p' apps/generator/docs/generator-template.md
sed -n '330,340p' apps/generator/docs/generator-template.mdRepository: asyncapi/generator
Length of output: 735
🏁 Script executed:
# Look for any documentation or changelog entries explaining why this template has a different version range
rg "1\.10\.0|3\.0\.1" apps/generator/ --type=md --type=jsonRepository: asyncapi/generator
Length of output: 1277
🏁 Script executed:
# Check the generator changelog for v3 introduction
rg "## 3\." apps/generator/CHANGELOG.md -A 20 | head -80Repository: asyncapi/generator
Length of output: 1376
🏁 Script executed:
# Look for v3 API first appearance in CHANGELOG
rg "v3|Parser.*API" apps/generator/CHANGELOG.md | head -20Repository: asyncapi/generator
Length of output: 104
🏁 Script executed:
# Check the exact context of both occurrences in generator-template.md
cat -n apps/generator/docs/generator-template.md | sed -n '115,340p'Repository: asyncapi/generator
Length of output: 11051
🌐 Web query:
AsyncAPI generator v3 API support minimum version 1.3.0 1.10.0 documentation
💡 Result:
I’m missing context—do you want (a) the AsyncAPI Generator v3 release/docs that state minimum supported AsyncAPI spec versions (e.g., 1.3.0 vs 1.10.0), (b) instructions for installing Generator v3 with a minimum dependency version, or (c) links to the specific AsyncAPI docs/pages? Which exactly do you want?
🌐 Web query:
AsyncAPI parser API v3 template compatibility generator version requirements
💡 Result:
Short answer
- To use Parser API v3 in a template, set apiVersion: "v3" in the template config (package.json "generator" property or .ageneratorrc). [1]
- The template must also declare a generator semver range it’s compatible with (the "generator" field) so the Generator CLI can validate compatibility. Use a Generator version that supports passing Parser v3 (use the Generator/CLI release that provides the new parser or run the CLI with the new-generator option if documented). [1][2]
- Example fix (package.json generator section): "apiVersion": "v3". This is the recommended way to make the Generator use parser-js v3 for AsyncAPI v3 specs. [3]
Sources
- Template configuration (apiVersion, generator compatibility, .ageneratorrc / package.json). [1]
- Generator vs template versioning and how generator validates template "generator" ranges; note about using the newer generator/CLI. [2]
- Community example showing setting apiVersion: "v3" to enable parser v3. [3]
Update generator version range to match documentation standard.
The apiVersion: v3 is correct for v3 Parser API support. However, the generator version range should be >=1.3.0 <3.0.0 to align with official template documentation. The current range >=1.10.0 <=3.0.1 is unnecessarily restrictive on the lower bound and uses an incorrect upper bound pattern (inclusive patch version instead of exclusive major version).
🤖 Prompt for AI Agents
In @apps/generator/docs/generator-template.md around lines 119 - 120, The
generator version range in the template is incorrect: update the "generator"
field to use the documented range format by changing its value from ">=1.10.0
<=3.0.1" to ">=1.3.0 <3.0.0" while keeping "apiVersion": "v3" as-is; locate the
"apiVersion" and "generator" entries in the template and replace the generator
string with the new lower bound >=1.3.0 and exclusive upper bound <3.0.0.
There was a problem hiding this comment.
actually update the value to >=2.0.0 <4.0.0, let us support latest AsyncAPI CLI v5
There was a problem hiding this comment.
@Harsh16gupta also update it in https://github.com/Harsh16gupta/asyncapi-v3-template-final
and please also commit the generated output to https://github.com/Harsh16gupta/asyncapi-v3-template-final
There was a problem hiding this comment.
@derberg done.
Updated the version range and reference repo. Please have a look.
There was a problem hiding this comment.
but you pushed [__transpiled](https://github.com/Harsh16gupta/asyncapi-v3-template-final/tree/main/__transpiled) which is the result of generator transpilation. I meant you should push the result of generation. Look at https://69669ff3b5b23637cad28600--asyncapi-website.netlify.app/docs/tools/generator/generator-template#4-write-script-to-run-the-test-code and output. You need to make sure the new tutorial works end to end - and I need to be able to verify how you tested it
There was a problem hiding this comment.
I followed the same flow as the v2 docs and ran npm test, which internally does:
asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ --output test/project- then runs
python test/project/test.py
The generated output for this tutorial is therefore test/project/client.py, and the runtime behavior is verified via test.py.
When I run this, I get exactly the same output as shown in the v2 tutorial logs (temperature dropped / risen messages), matching the expected behavior:
https://69669ff3b5b23637cad28600--asyncapi-website.netlify.app/docs/tools/generator/generator-template#5d-update-asyncapi-document:~:text=Run%20npm%20test%20to%20validate%20that%20everything,Where%20to%20go%20from%20here%3F
This confirms that the v2 → v3 conversion works end to end, and test/project is already committed in the repo so the generated output and verification steps are visible. I’ve also removed __transpiled since it’s not part of the generated output.
Please let me know if there’s any additional generated artifact you expect beyond test/project.
There was a problem hiding this comment.
@derberg
I tried dong this
and I have commited the output generated to this
https://github.com/Harsh16gupta/Testing
Just wanted to confirm if this is what you were asking me to do
|
|
Hi @derberg, just checking in on this PR |
derberg
left a comment
derberg
left a comment
There was a problem hiding this comment.
great work, sorry for such lengthy review
last thing - at the bottom of the document you see a link to my repo and my article:
- please change repo link to yours https://github.com/Harsh16gupta/asyncapi-v3-template-final
- please remove link to my outdated article
|
|
Thanks for the review |
|
/rtm |
3 participants
What this PR does
This PR updates the “Creating a template – Python” tutorial to be fully based on AsyncAPI v3.
It:
host()instead ofurl())Validation
Before opening this PR, I followed the updated tutorial end-to-end and generated a working Python MQTT client using AsyncAPI v3.
The complete working reference implementation is available here:
https://github.com/Harsh16gupta/asyncapi-v3-template-final
Using this repo, reviewers can:
Validation output
Screenshots of successful generation and execution are available here:
Related issue
Resolves #1503
Summary by CodeRabbit
New Features
Updates
Documentation