docs: rewrite Java template tutorial to AsyncAPI v3#5250
docs: rewrite Java template tutorial to AsyncAPI v3#5250wei123-web wants to merge 4 commits intoasyncapi:masterfrom
Conversation
Corrected typos and improved clarity in instructions and notes throughout the document.
wei123-web
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve,
derberg,
princerajpoot20,
sambhavgupta0705 and
thulieblack
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughRemoved a duplicated word in a Java template example and added two documentation pages: a Java AsyncAPI generator template guide and a Reusable Components API reference for Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 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 |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #5250 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 830 830
Branches 159 159
=========================================
Hits 830 830 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-5250--asyncapi-website.netlify.app/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
pages/docs/tools/generator/generator-template-java.mdx (1)
36-36: Minor grammar improvement.Consider changing "from root directory" to "at the root directory" for clarity.
📝 Suggested fix
- 6. Create a new file named **index.js** in a `template` folder from root directory. This file is used to define the **logic** for your template. + 6. Create a new file named **index.js** in a `template` folder at the root directory. This file is used to define the **logic** for your template.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/docs/tools/generator/generator-template-java.mdx` at line 36, Update the sentence that reads "Create a new file named **index.js** in a `template` folder in the root directory." to use "at the root directory" for clarity; locate the sentence mentioning "index.js" and the `template` folder in generator-template-java.mdx and replace "in the root directory" with "at the root directory" so the phrasing becomes "Create a new file named **index.js** in a `template` folder at the root directory."
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Line 318: The phrase "Similar to the previous `TopicFunction` function" is
misleading because this is the first introduction of TopicFunction; update the
sentence in generator-template-java.mdx to either remove "previous" or clarify
the reference (for example: "Similar to the Python tutorial's `TopicFunction`"
or "As with the earlier example in the Python tutorial, `TopicFunction`...") so
readers understand whether this is a new definition or a cross-language
reference; edit the sentence containing `TopicFunction` to use one of those
clearer phrasings.
- Around line 475-484: The template uses asyncapi.operations().filterByReceive()
(in TopicFunction) but the AsyncAPI operations temperatureDrop and
temperatureRise are defined with action: send, so no operations are matched;
either change the operations' action values to receive for temperatureDrop and
temperatureRise (so they align with filterByReceive()), or update the template
call in TopicFunction to use filterBySend() so it matches the existing action:
send operations—make the change consistently wherever TopicFunction filters
operations.
- Line 137: Replace the grammatically incorrect phrase "to pasted into" with "to
paste into" in the sentence that introduces the sample Client.java code (the
line that starts "Here is the sample code to pasted into the `Client.java`
file..."); update the sentence to read "Here is the sample code to paste into
the `Client.java` file you generated above by running the `asyncapi generate
fromTemplate src/fixtures/asyncapi.yml ./ --output src/main/java` command."
- Line 129: Fix the typo in the sentence starting with "**repositories** - This
section tells your app to fetch dependencies from Maven Central to retrieve the
MQTT client library." by changing "you app" to "your app" so the sentence reads
"...tells your app to fetch dependencies..."; locate the sentence containing the
"**repositories**" heading in generator-template-java.mdx and update the text
accordingly.
- Line 396: Update the BROKER_URL constant so it includes the protocol scheme
instead of only host: replace the current construction using server.host() with
a value that prefixes the protocol (e.g., "tcp://" + server.host()) or, better,
use the server.protocol() accessor to build the full URL (e.g.,
server.protocol() + "://" + server.host()) so the BROKER_URL constant contains a
complete broker URL for the Eclipse Paho MQTT client.
---
Nitpick comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Line 36: Update the sentence that reads "Create a new file named **index.js**
in a `template` folder in the root directory." to use "at the root directory"
for clarity; locate the sentence mentioning "index.js" and the `template` folder
in generator-template-java.mdx and replace "in the root directory" with "at the
root directory" so the phrasing becomes "Create a new file named **index.js** in
a `template` folder at the root directory."
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: bfcb0c54-11ee-4727-98aa-3b3f53b67943
📒 Files selected for processing (2)
markdown/docs/tools/generator/generator-template-java.mdpages/docs/tools/generator/generator-template-java.mdx
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
pages/docs/tools/generator/generator-template-java.mdx (1)
318-318:⚠️ Potential issue | 🟡 MinorClarify reference to "previous" TopicFunction.
The text mentions "Similar to the previous
TopicFunctionfunction" but this is the first timeTopicFunctionis created in this tutorial. Also, "asyncAPI" should be capitalized as "AsyncAPI" for consistency.📝 Suggested fix
-Similar to the previous `TopicFunction` function we will create a function to make reusable components regardless of the number of channels in the asyncAPI v3 document. +We will create a `TopicFunction` to make reusable components regardless of the number of channels in the AsyncAPI v3 document.,
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/docs/tools/generator/generator-template-java.mdx` at line 318, Update the sentence that currently reads "Similar to the previous `TopicFunction` function..." to remove the incorrect "previous" reference and instead introduce `TopicFunction` as a new construct (e.g., "We will now create a `TopicFunction`..."), and change all occurrences of "asyncAPI" to the correctly capitalized "AsyncAPI" for consistency; ensure the paragraph clearly explains that `TopicFunction` is being created here for reusable components across channels and does not refer to any prior definition.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Around line 383-387: The TopicFunction component is re-filtering the already
send-only operations with operations.filterByReceive(), producing an empty set;
update TopicFunction (the TopicFunction function) to either call
operations.filterBySend() instead of filterByReceive() or remove the redundant
filtering and iterate the passed-in operations directly (use the existing
operations parameter as the source of truth), and update any related comment
that states it filters receive operations to reflect the new behavior.
---
Duplicate comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Line 318: Update the sentence that currently reads "Similar to the previous
`TopicFunction` function..." to remove the incorrect "previous" reference and
instead introduce `TopicFunction` as a new construct (e.g., "We will now create
a `TopicFunction`..."), and change all occurrences of "asyncAPI" to the
correctly capitalized "AsyncAPI" for consistency; ensure the paragraph clearly
explains that `TopicFunction` is being created here for reusable components
across channels and does not refer to any prior definition.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 005eed0b-25d6-41b9-8603-54b1cf11b60d
📒 Files selected for processing (1)
pages/docs/tools/generator/generator-template-java.mdx
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Around line 349-350: Update the tutorial commentary to match the actual
implementation which filters by send operations: replace mentions of "receive",
"subscribed" or "subscription" with "send" or "published" and clarify that the
function returns a list of objects for each send operation (each containing
properties `name` and `topic`), where `name` holds the AsyncAPI `operationId`;
also update the other occurrences referenced (around the `filterBySend()` usage
and generated `send...` methods) so the wording consistently reflects
send/publish semantics rather than receive/subscribe.
- Around line 299-304: The sample TestClient contains an unbounded loop (while
(true)) that causes npm test to never complete; update the TestClient main loop
to be bounded or conditional: replace the infinite loop with a loop limited by a
counter or a configurable timeout/env var (e.g., MAX_ITERATIONS or RUN_TIME_MS)
and ensure the main method (TestClient) exits cleanly after the bound is
reached; keep the existing behavior by default but allow overriding via a
parameter so the tutorial verification flow (npm test) can finish.
- Around line 396-397: The current BROKER_URL built from server.protocol()
yields "mqtt://" which Eclipse Paho doesn't accept; change the code that
constructs BROKER_URL to convert or map incoming protocol "mqtt" to a supported
scheme (e.g., "tcp") before concatenation so BROKER_URL becomes
"tcp://{server.host()". Update any AsyncAPI protocol field generation (where
protocol: mqtt is set) to emit "tcp" instead of "mqtt" and adjust the documented
expected output examples to show "tcp://..."; touch the symbols BROKER_URL and
any generator logic that reads server.protocol() and the AsyncAPI protocol
emission to perform this mapping.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 14eddd1a-424c-4657-813a-3a7284fffca8
📒 Files selected for processing (1)
pages/docs/tools/generator/generator-template-java.mdx
There was a problem hiding this comment.
🧹 Nitpick comments (2)
pages/docs/tools/generator/generator-template-java.mdx (2)
356-360: Variable name inconsistent with filter method.The variable is named
receiveOperationsbut it's assigned fromoperations.filterBySend(). This naming mismatch can confuse developers following the tutorial.📝 Proposed fix
function getTopicsFromOperations(operations) { - const receiveOperations = operations.filterBySend(); + const sendOperations = operations.filterBySend(); let topicsDetails = [] - receiveOperations.forEach((op) => { + sendOperations.forEach((op) => { const topic = {}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/docs/tools/generator/generator-template-java.mdx` around lines 356 - 360, In getTopicsFromOperations, the variable receiveOperations is misnamed because it is assigned from operations.filterBySend(); rename the variable to sendOperations (or otherwise ensure the variable name matches the filter method) wherever it appears in that function to eliminate the mismatch and avoid confusion between filterBySend and receiveOperations.
376-384: Terminology mismatch between comment/text and code.Line 376 mentions the application is "subscribed to" topics, and Line 383 comment says "Get receive operations", but the code uses
filterBySend()which filters for send (publish) operations. This inconsistency can confuse readers learning AsyncAPI v3 semantics.📝 Proposed fix
-Import the `TopicFunction` component in your template code in **index.js** and add the template code to generate the functions for the topics which the `Temperature Service` application is subscribed to. In your case, the final version of your template code should look like this: +Import the `TopicFunction` component in your template code in **index.js** and add the template code to generate the functions for the topics that the `Temperature Service` application publishes to. In your case, the final version of your template code should look like this:export default function ({ asyncapi, params }) { - // v3: Get receive operations instead of channels + // v3: Get send operations instead of channels const operations = asyncapi.operations().filterBySend();🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/docs/tools/generator/generator-template-java.mdx` around lines 376 - 384, The documentation text and comment refer to the app being "subscribed to" topics and "Get receive operations" but the template code uses asyncapi.operations().filterBySend(); update the template in index.js to use the receive-filtering API (e.g., asyncapi.operations().filterByReceive()) and ensure the surrounding explanatory text mentions "subscribed to" topics and "receive" operations; locate the TopicFunction import and the default export function and replace filterBySend() with the appropriate receive/filterByReceive() call so code and prose match AsyncAPI v3 semantics.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@pages/docs/tools/generator/generator-template-java.mdx`:
- Around line 356-360: In getTopicsFromOperations, the variable
receiveOperations is misnamed because it is assigned from
operations.filterBySend(); rename the variable to sendOperations (or otherwise
ensure the variable name matches the filter method) wherever it appears in that
function to eliminate the mismatch and avoid confusion between filterBySend and
receiveOperations.
- Around line 376-384: The documentation text and comment refer to the app being
"subscribed to" topics and "Get receive operations" but the template code uses
asyncapi.operations().filterBySend(); update the template in index.js to use the
receive-filtering API (e.g., asyncapi.operations().filterByReceive()) and ensure
the surrounding explanatory text mentions "subscribed to" topics and "receive"
operations; locate the TopicFunction import and the default export function and
replace filterBySend() with the appropriate receive/filterByReceive() call so
code and prose match AsyncAPI v3 semantics.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 975ca191-bd42-45d3-83c7-ce238482f424
📒 Files selected for processing (1)
pages/docs/tools/generator/generator-template-java.mdx
wei123-web
force-pushed
the
docs/rewrite-java-template-tutorial-v3
branch
from
de7c049 to
ad19d49
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
pages/docs/tools/generator/api_components.mdx (1)
8-1230: Consider generating this API reference from source metadata to reduce drift.This page is comprehensive, but fully manual duplication of component signatures/examples is high-maintenance and can go stale as
@asyncapi/generator-componentsevolves. Consider generating this page (or key sections) from a single source of truth (typed metadata/JSDoc/export map).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pages/docs/tools/generator/api_components.mdx` around lines 8 - 1230, The docs page is manually duplicating many component signatures (e.g., CloseConnection, Connect, DependencyProvider, MethodGenerator, Models, Readme, SendOperations) which risks drift; replace the manual API reference with a generated one by extracting typed metadata/JSDoc from the `@asyncapi/generator-components` package and emitting the MDX sections programmatically. Implement a generation script that reads exports and JSDoc/type metadata for symbols like CloseConnection, MethodGenerator, AvailableOperations, Readme, etc., produces the parameter/return/examples blocks, and writes/updates pages/docs/tools/generator/api_components.mdx (or an included partial) as part of the docs build; add the script to package.json and CI so the file is regenerated on changes to the source metadata. Ensure generated content preserves examples and headings used by the current MDX structure and include a short header in the file indicating it is generated.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pages/docs/tools/generator/api_components.mdx`:
- Line 79: Remove the accidental review artifact text "Expand commentComment on
lines R76 to R79Resolved" from pages/docs/tools/generator/api_components.mdx;
open the MDX file, locate that exact string (currently at the stray line in the
API components section), delete the line so only intended documentation content
remains, save and run the docs build/linter to confirm no other review-residue
remains.
---
Nitpick comments:
In `@pages/docs/tools/generator/api_components.mdx`:
- Around line 8-1230: The docs page is manually duplicating many component
signatures (e.g., CloseConnection, Connect, DependencyProvider, MethodGenerator,
Models, Readme, SendOperations) which risks drift; replace the manual API
reference with a generated one by extracting typed metadata/JSDoc from the
`@asyncapi/generator-components` package and emitting the MDX sections
programmatically. Implement a generation script that reads exports and
JSDoc/type metadata for symbols like CloseConnection, MethodGenerator,
AvailableOperations, Readme, etc., produces the parameter/return/examples
blocks, and writes/updates pages/docs/tools/generator/api_components.mdx (or an
included partial) as part of the docs build; add the script to package.json and
CI so the file is regenerated on changes to the source metadata. Ensure
generated content preserves examples and headings used by the current MDX
structure and include a short header in the file indicating it is generated.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 8023b4b9-c635-467d-9ad7-c823bdcb3a83
📒 Files selected for processing (1)
pages/docs/tools/generator/api_components.mdx
wei123-web
force-pushed
the
docs/rewrite-java-template-tutorial-v3
branch
from
04138e0 to
907c8f1
Compare
|
|
@wei123-web I cannot seem to find the linked issue for this PR. cc: @princerajpoot20 |
|
@animeshk923 This PR addresses asyncapi/generator#1828. Since the issue is in the generator repo and the fix is in the website repo, I’ve now added Closes asyncapi/generator#1828 to the PR description for proper linking. |
|
@princerajpoot20 Correct me if I'm wrong, but my learning from a previous issue that I recently resolved, the documentation needs to be updated here I guess: https://github.com/asyncapi/generator/blob/master/apps/generator/docs/generator-template-java.md |
hi @animeshk923, i think you are correct! The documentation in the generator repo at apps/generator/docs/generator-template-java.md also needs to be updated. I will open a separate PR in the generator repo |
@wei123-web cc: @princerajpoot20 |
Thanks! I’ve opened a new PR in the generator repository (#2029) with these changes. Closing this one. |
github-project-automation
Bot
moved this from To Be Triaged
to Done
in Website - Kanban
4 participants
Description
Rewrites the "Creating a template – Java" tutorial to use AsyncAPI v3.
Resolves #1828
Note: This PR updates the documentation in the website repository to fix issue #1828 (opened in the generator repository).
Summary by CodeRabbit
Bug Fixes
Documentation
Closes asyncapi/generator#1828