docs(tutorial): fix broken links in coming from api #4264
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bandantonio
requested review from
TRohit20,
asyncapi-bot-eve 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. |
Contributor
WalkthroughThe documentation for the "Coming from OpenAPI" tutorial was updated to correct several broken or outdated URLs, replacing them with accurate and current links for Darrel Miller's blog post and AsyncAPI specification references. No changes were made to code or exported/public entities. Changes
Suggested labels
Suggested reviewers
Poem
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #4264 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-4264--asyncapi-website.netlify.app/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/tutorials/getting-started/coming-from-openapi.md(2 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/fixtures/markdown/check-edit-links-data.js:3-11
Timestamp: 2025-01-19T04:51:41.255Z
Learning: In the AsyncAPI website repository, the test data in `tests/fixtures/markdown/check-edit-links-data.js` intentionally includes inconsistent paths (with and without 'docs' prefix) to verify the script's ability to normalize and handle ambiguous path structures.
Learnt from: asyncapi-bot
PR: asyncapi/website#0
File: :0-0
Timestamp: 2025-02-18T12:07:42.211Z
Learning: The following PR commands are supported in the asyncapi/website repository:
- `/please-take-a-look` or `/ptal`: Requests attention from reviewers who haven't reviewed the PR
- `/ready-to-merge` or `/rtm`: Triggers automerge when all conditions are met
- `/do-not-merge` or `/dnm`: Blocks automerge even if all conditions are met
- `/autoupdate` or `/au`: Adds autoupdate label to keep PR in sync with target branch
- `/update` or `/u`: One-time update of PR with latest changes from target branch
Learnt from: bandantonio
PR: asyncapi/website#3393
File: markdown/blog/2024-Q1-docs-report.md:10-12
Timestamp: 2024-11-13T20:34:18.998Z
Learning: In the markdown files for the AsyncAPI website, avatar image paths should be referenced without the `public` prefix (e.g., use `/img/avatars/...` instead of `/public/img/avatars/...`).
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/markdown/check-edit-links.test.js:20-46
Timestamp: 2025-01-14T14:58:38.076Z
Learning: In the AsyncAPI website codebase, the edit-page-config.json contains a fallback match entry that ensures determineEditLink function always has a valid target.value, making null checks unnecessary.
Learnt from: anshgoyalevil
PR: asyncapi/website#3950
File: scripts/utils/check-locales.ts:122-129
Timestamp: 2025-04-20T16:05:16.482Z
Learning: In the AsyncAPI website project, Next.js throws errors at runtime when locale files are missing, making additional validation for missing files unnecessary in the check-locales script.
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: scripts/markdown/check-edit-links.js:83-88
Timestamp: 2025-01-14T15:12:29.840Z
Learning: In the AsyncAPI website's edit link generation logic, the `editUrls` configuration (config/edit-page-config.json) includes a fallback entry with an empty value that acts as a catch-all matcher. Therefore, `editOptions.find()` will always return a match, making null checks on the result unnecessary and untestable.
markdown/docs/tutorials/getting-started/coming-from-openapi.md (9)
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/fixtures/markdown/check-edit-links-data.js:3-11
Timestamp: 2025-01-19T04:51:41.255Z
Learning: In the AsyncAPI website repository, the test data in `tests/fixtures/markdown/check-edit-links-data.js` intentionally includes inconsistent paths (with and without 'docs' prefix) to verify the script's ability to normalize and handle ambiguous path structures.
Learnt from: bandantonio
PR: asyncapi/website#3393
File: markdown/blog/2024-Q1-docs-report.md:10-12
Timestamp: 2024-11-13T20:34:18.998Z
Learning: In the markdown files for the AsyncAPI website, avatar image paths should be referenced without the `public` prefix (e.g., use `/img/avatars/...` instead of `/public/img/avatars/...`).
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/markdown/check-edit-links.test.js:20-46
Timestamp: 2025-01-14T14:58:38.076Z
Learning: In the AsyncAPI website codebase, the edit-page-config.json contains a fallback match entry that ensures determineEditLink function always has a valid target.value, making null checks unnecessary.
Learnt from: anshgoyalevil
PR: asyncapi/website#3950
File: scripts/utils/check-locales.ts:122-129
Timestamp: 2025-04-20T16:05:16.482Z
Learning: In the AsyncAPI website project, Next.js throws errors at runtime when locale files are missing, making additional validation for missing files unnecessary in the check-locales script.
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: scripts/markdown/check-edit-links.js:83-88
Timestamp: 2025-01-14T15:12:29.840Z
Learning: In the AsyncAPI website's edit link generation logic, the `editUrls` configuration (config/edit-page-config.json) includes a fallback entry with an empty value that acts as a catch-all matcher. Therefore, `editOptions.find()` will always return a match, making null checks on the result unnecessary and untestable.
Learnt from: iambami
PR: asyncapi/website#4111
File: markdown/blog/community-spotlight-aayush.md:3-3
Timestamp: 2025-06-03T06:48:09.304Z
Learning: For AsyncAPI community spotlight blog posts, the frontmatter date should reflect the actual publication date, not the month being highlighted in the spotlight. For example, a "May Community Spotlight" can be published in June with a June date in the frontmatter.
Learnt from: TRohit20
PR: asyncapi/website#4107
File: markdown/docs/tools/studio/architecture.md:23-23
Timestamp: 2025-05-09T17:35:57.171Z
Learning: In the AsyncAPI Studio architecture documentation, "Layer Breakdown" is intentionally structured as an H3 heading (subsection) because it provides additional detail about the layered architecture pattern introduced earlier, rather than being a standalone main section.
Learnt from: akshatnema
PR: asyncapi/website#3423
File: tests/index.test.js:2-7
Timestamp: 2025-01-18T08:44:43.614Z
Learning: In the AsyncAPI website project, JavaScript test files must include the .ts extension when importing TypeScript files (e.g., `require('../scripts/build-rss.ts')`). This is a project-specific requirement enforced by the linting rules and build setup, even though it differs from typical Node.js behavior.
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: scripts/markdown/check-editlinks.js:58-59
Timestamp: 2025-01-08T15:15:00.759Z
Learning: In the AsyncAPI codebase, batch processing operations (like in the Dashboard script and check-editlinks.js) follow a sequential pattern using await in loops, which is the preferred approach for maintaining consistency across the codebase.
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Test NodeJS PR - windows-latest
- GitHub Check: Lighthouse CI
🔇 Additional comments (1)
markdown/docs/tutorials/getting-started/coming-from-openapi.md (1)
8-8: 👍 Canonical blog URL looks goodSwitching to
https://www.openapis.org/blog/…removes the stale/news/blogs/prefix and resolves correctly.
Comment on lines
+24
to
+25
| 1. The [AsyncAPI server object](/docs/reference/specification/latest#serverObject) is almost identical to its OpenAPI counterpart, with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. AsyncAPI supports multiple protocols, not only HTTP, like in the case of OpenAPI. | ||
| 1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/reference/specification/latest#parameterObject) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/reference/specification/latest#messageObject). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters. |
Contributor
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify that the new “latest” spec anchors resolve
Great call switching to the un-versioned /docs/reference/specification/latest path for maintainability.
The slug generator for the spec pages sometimes lower-cases and hyphenates headings (e.g. server-object). Please confirm that
#serverObject#parameterObject#messageObject
still land on the intended sections; otherwise adjust the anchors.
🏁 Script executed:
#!/usr/bin/env bash
# Check that the expected IDs exist in the rendered HTML.
for id in serverObject parameterObject messageObject; do
echo "Searching for id=\"$id\" …"
curl -s https://www.asyncapi.com/docs/reference/specification/latest | grep -n "id=\"$id\"" || \
echo "❌ Anchor $id not found"
doneLength of output: 937
🏁 Script executed:
#!/usr/bin/env bash
# Verify if the spec headings use hyphenated, lower-case IDs instead of camelCase.
for id in server-object parameter-object message-object; do
echo "Searching for id=\"$id\" …"
curl -s https://www.asyncapi.com/docs/reference/specification/latest | grep -n "id=\"$id\"" || \
echo "❌ Anchor $id not found"
doneLength of output: 961
🏁 Script executed:
#!/usr/bin/env bash
# Extract all id values (single or double quoted) containing server, parameter, or message
curl -s https://www.asyncapi.com/docs/reference/specification/latest \
| sed -n "s/.*id=['\"]\([^'\"]*\)['\"].*/\1/p" \
| grep -i -E 'server|parameter|message' \
| sort -uLength of output: 173
🏁 Script executed:
#!/usr/bin/env bash
# Inspect id attributes and heading tags to determine actual anchor patterns
curl -s https://www.asyncapi.com/docs/reference/specification/latest \
| grep -n -E 'id=|<h[2-3]' \
| head -n 100Length of output: 111
🏁 Script executed:
#!/usr/bin/env bash
# Follow redirects and include trailing slash to ensure HTML is retrieved
curl -sL https://www.asyncapi.com/docs/reference/specification/latest/ \
| grep -o 'id="[a-zA-Z0-9-]*"' \
| sed 's/id="//;s/"//' \
| sort -uLength of output: 3504
Update spec reference anchors to match hyphenated IDs
The spec pages use hyphenated, lowercase IDs (server-object, parameter-object, message-object), so the links need to be updated:
• File: markdown/docs/tutorials/getting-started/coming-from-openapi.md
• Lines: 24–25
- 1. The [AsyncAPI server object](/docs/reference/specification/latest#serverObject) is almost identical to its OpenAPI counterpart…
+ 1. The [AsyncAPI server object](/docs/reference/specification/latest#server-object) is almost identical to its OpenAPI counterpart…
- 1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/reference/specification/latest#parameterObject) are a bit different…
+ 1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/reference/specification/latest#parameter-object) are a bit different…
…defined in the [message object](/docs/reference/specification/latest#messageObject). Therefore…should become:
- …defined in the [message object](/docs/reference/specification/latest#messageObject). Therefore…
+ …defined in the [message object](/docs/reference/specification/latest#message-object). Therefore…📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 1. The [AsyncAPI server object](/docs/reference/specification/latest#serverObject) is almost identical to its OpenAPI counterpart, with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. AsyncAPI supports multiple protocols, not only HTTP, like in the case of OpenAPI. | |
| 1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/reference/specification/latest#parameterObject) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/reference/specification/latest#messageObject). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters. | |
| 1. The [AsyncAPI server object](/docs/reference/specification/latest#server-object) is almost identical to its OpenAPI counterpart, with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. AsyncAPI supports multiple protocols, not only HTTP, like in the case of OpenAPI. | |
| 1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/reference/specification/latest#parameter-object) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/reference/specification/latest#message-object). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters. |
🤖 Prompt for AI Agents
In markdown/docs/tutorials/getting-started/coming-from-openapi.md around lines
24 to 25, update the spec reference anchors in the links to use hyphenated,
lowercase IDs instead of camelCase. Change
"/docs/reference/specification/latest#serverObject" to
"/docs/reference/specification/latest#server-object",
"/docs/reference/specification/latest#parameterObject" to
"/docs/reference/specification/latest#parameter-object", and
"/docs/reference/specification/latest#messageObject" to
"/docs/reference/specification/latest#message-object" to match the actual spec
page IDs.
Collaborator
Author
There was a problem hiding this comment.
It's ok to use references in camelCase
Contributor
There was a problem hiding this comment.
@bandantonio Thank you for the clarification! I understand that camelCase references are acceptable in the AsyncAPI documentation. The current anchor format (#serverObject, #parameterObject, #messageObject) in the links is correct as implemented.
(\ /)
( ._. )
o_(")(")
Understanding noted!
✏️ Learnings added
Learnt from: bandantonio
PR: asyncapi/website#4264
File: markdown/docs/tutorials/getting-started/coming-from-openapi.md:24-25
Timestamp: 2025-07-19T20:58:34.002Z
Learning: In the AsyncAPI website documentation, anchor references to specification sections can use camelCase format (e.g., #serverObject, #parameterObject, #messageObject) even if the actual HTML IDs on the spec page use hyphenated lowercase format. This is acceptable and should not be changed.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/fixtures/markdown/check-edit-links-data.js:3-11
Timestamp: 2025-01-19T04:51:41.255Z
Learning: In the AsyncAPI website repository, the test data in `tests/fixtures/markdown/check-edit-links-data.js` intentionally includes inconsistent paths (with and without 'docs' prefix) to verify the script's ability to normalize and handle ambiguous path structures.
Learnt from: bandantonio
PR: asyncapi/website#3393
File: markdown/blog/2024-Q1-docs-report.md:10-12
Timestamp: 2024-11-13T20:34:18.998Z
Learning: In the markdown files for the AsyncAPI website, avatar image paths should be referenced without the `public` prefix (e.g., use `/img/avatars/...` instead of `/public/img/avatars/...`).
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/markdown/check-edit-links.test.js:20-46
Timestamp: 2025-01-14T14:58:38.076Z
Learning: In the AsyncAPI website codebase, the edit-page-config.json contains a fallback match entry that ensures determineEditLink function always has a valid target.value, making null checks unnecessary.
Learnt from: akshatnema
PR: asyncapi/website#3265
File: tests/fixtures/toolsObjectData.js:51-52
Timestamp: 2024-10-09T17:35:36.557Z
Learning: When reviewing code in the 'asyncapi/website' repository, akshatnema prefers that I do not provide committable code suggestions.
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: scripts/markdown/check-edit-links.js:83-88
Timestamp: 2025-01-14T15:12:29.840Z
Learning: In the AsyncAPI website's edit link generation logic, the `editUrls` configuration (config/edit-page-config.json) includes a fallback entry with an empty value that acts as a catch-all matcher. Therefore, `editOptions.find()` will always return a match, making null checks on the result unnecessary and untestable.
Learnt from: akshatnema
PR: asyncapi/website#3378
File: scripts/markdown/check-markdown.js:1-1
Timestamp: 2024-11-25T18:34:51.303Z
Learning: When reviewing `scripts/markdown/check-markdown.js`, optimizations should be addressed in separate issues and not included in the current pull request.
Learnt from: asyncapi-bot
PR: asyncapi/website#0
File: :0-0
Timestamp: 2025-02-18T12:07:42.211Z
Learning: The following PR commands are supported in the asyncapi/website repository:
- `/please-take-a-look` or `/ptal`: Requests attention from reviewers who haven't reviewed the PR
- `/ready-to-merge` or `/rtm`: Triggers automerge when all conditions are met
- `/do-not-merge` or `/dnm`: Blocks automerge even if all conditions are met
- `/autoupdate` or `/au`: Adds autoupdate label to keep PR in sync with target branch
- `/update` or `/u`: One-time update of PR with latest changes from target branch
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: scripts/markdown/check-editlinks.js:80-93
Timestamp: 2025-01-14T09:23:32.728Z
Learning: In the AsyncAPI website's edit link generation system, the `editOptions` array in `edit-page-config.json` includes a fallback entry with an empty string value (`''`) that matches any URL path, ensuring that `determineEditLink()` function always finds a target and never returns null.
Learnt from: iambami
PR: asyncapi/website#4111
File: markdown/blog/community-spotlight-aayush.md:3-3
Timestamp: 2025-06-03T06:48:09.304Z
Learning: For AsyncAPI community spotlight blog posts, the frontmatter date should reflect the actual publication date, not the month being highlighted in the spotlight. For example, a "May Community Spotlight" can be published in June with a June date in the frontmatter.
thulieblack
approved these changes
Jul 23, 2025
Member
|
/rtm |
sambhavgupta0705
approved these changes
Jul 23, 2025
Member
|
/rtm |
Member
|
/rtm |
Member
|
/rtm |
This was referenced Jul 24, 2025
This was referenced Jul 28, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related issue(s)
Fixes #4225
Closes #4233
Summary by CodeRabbit