Open
Conversation
NethmiRanasinghe
requested review from
chamilaadhi and
tharikaGitHub
as code owners
WalkthroughDocumentation updates for streaming API creation workflows to support AsyncAPI v3.0.0 specifications and reflect UI terminology changes from Publish/Subscribe to Send/Receive operations. Includes a new AsyncAPI v3 example file, WSDL URL generation security configurations, and related tutorial updates. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 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: 4
🧹 Nitpick comments (1)
en/docs/install-and-setup/setup/deployment-best-practices/security-guidelines-for-production-deployment.md (1)
357-379: Syncurl_generation_secretinto the config catalog to avoid doc drift.This section is solid, but the authoritative config reference should also document this new
[apim.devportal]key; otherwise users may miss it when usingen/docs/reference/config-catalog.md.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/docs/install-and-setup/setup/deployment-best-practices/security-guidelines-for-production-deployment.md` around lines 357 - 379, Add the new config key to the authoritative config catalog: document the [apim.devportal] section and the url_generation_secret key in the config-catalog so it doesn't drift from the guide; include a short description (secret used to sign/secure generated WSDL URLs), type (string), recommended length/strength (>=32 chars), an example value placeholder, and a note to store it in the secure vault (referencing the Encrypting Passwords guidance) so readers of config-catalog will see the same setting described in the Security Guidelines section.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-streaming-api-from-an-asyncapi-definition.md`:
- Around line 74-80: Update the wording in the Topics step by replacing the
phrase "provided URL" with a source-agnostic term such as "provided AsyncAPI
definition" (or "provided definition") so the sentence no longer assumes upload
method; find the paragraph containing "topics have been created automatically
from the AsyncAPI definition specified in the provided URL" and change it to use
the new phrase so it matches both file upload and URL inputs.
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websocket-streaming-api.md`:
- Line 180: The image filename in the Markdown uses a typo
("wesocket-streaming-api-v3-add-topic-url-mapping.png") which likely breaks the
screenshot link; update the src and href occurrences to the correct filename
"websocket-streaming-api-v3-add-topic-url-mapping.png" in the line containing
the <a
href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png">
and the <img
src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png">
references so both link and image point to the corrected file name.
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websub-streaming-api.md`:
- Line 84: Fix the typo in the documented default operation name: change the
operation string from "receive__edfault" to "receive__default" in the sentence
that describes the default channel `_default` so it reads that the `_default`
channel has a default operation `receive__default`.
In
`@en/docs/api-developer-portal/invoke-apis/invoke-apis-using-tools/invoke-an-api-using-a-soap-client.md`:
- Around line 30-38: Update the wording in Step 8 to be clearer and match UI
terminology: change "Give your API's WSDL" to "Provide your API's WSDL", change
"in published state" to "published", change "will get expired" to "will expire",
and replace "restricted visibility" with the exact UI label "Restricted by
roles"; ensure the two bullets under Step 8 and any related sentences use these
revised phrases for consistency (locate the Step 8 block in the
invoke-an-api-using-a-soap-client.md content and update the sentence fragments
accordingly).
---
Nitpick comments:
In
`@en/docs/install-and-setup/setup/deployment-best-practices/security-guidelines-for-production-deployment.md`:
- Around line 357-379: Add the new config key to the authoritative config
catalog: document the [apim.devportal] section and the url_generation_secret key
in the config-catalog so it doesn't drift from the guide; include a short
description (secret used to sign/secure generated WSDL URLs), type (string),
recommended length/strength (>=32 chars), an example value placeholder, and a
note to store it in the secure vault (referencing the Encrypting Passwords
guidance) so readers of config-catalog will see the same setting described in
the Security Guidelines section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b6241ad8-f75e-4c40-8453-727936212522
⛔ Files ignored due to path filters (34)
en/docs/assets/attachments/103332601/asyncv3-def-view.pngis excluded by!**/*.pngen/docs/assets/attachments/103332601/asyncv3-file.pngis excluded by!**/*.pngen/docs/assets/attachments/103332601/asyncv3-topics-page.pngis excluded by!**/*.pngen/docs/assets/attachments/103332601/wsdl-url.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/asyncv3-operations.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/asyncv3-topics.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-add-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-asyncapi.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-create-new-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-delete-default-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-new-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-newly-added-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/sse-api-v3-topics.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-channel.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-asyncapi.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-delete-topic-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-channel.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-topics.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-add-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-add-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-asyncapi.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-delete-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-new-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-newly-added-topic.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-operation.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/websub-api-v3-topics.pngis excluded by!**/*.pngen/docs/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.pngis excluded by!**/*.pngen/docs/assets/img/tutorials/streaming-api/enable-secret-generation-v3.pngis excluded by!**/*.pngen/docs/assets/img/tutorials/streaming-api/websocket-api-v3-add-topics.pngis excluded by!**/*.pngen/docs/assets/img/tutorials/streaming-api/websocket-api-v3-topic-url-mapping.pngis excluded by!**/*.png
📒 Files selected for processing (10)
en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-sse-streaming-api.mden/docs/api-design-manage/design/create-api/create-streaming-api/create-a-streaming-api-from-an-asyncapi-definition.mden/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websocket-streaming-api.mden/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websub-streaming-api.mden/docs/api-developer-portal/invoke-apis/invoke-apis-using-tools/invoke-an-api-using-a-soap-client.mden/docs/assets/attachments/103332601/streetlights_v3-def.ymlen/docs/install-and-setup/setup/deployment-best-practices/production-deployment-guidelines.mden/docs/install-and-setup/setup/deployment-best-practices/security-guidelines-for-production-deployment.mden/docs/tutorials/streaming-api/create-and-publish-websocket-api.mden/docs/tutorials/streaming-api/create-and-publish-websub-api.md
Comment on lines
+74
to
+80
| []({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-topics.png) | ||
|
|
||
| You will notice that the topics have been created automatically from the AsyncAPI definition specified in the provided URL. | ||
|
|
||
| []({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-operations.png) | ||
|
|
||
| Expand each topic to view the operations which are automatically created for each channel, as defined in the specification. |
There was a problem hiding this comment.
Fix source wording mismatch in Topics step.
Line 76 still says topics are created from the “provided URL”, but this walkthrough now uses file upload (Lines 40-42). Please make the sentence source-agnostic (e.g., “provided AsyncAPI definition”).
✏️ Proposed text fix
-You will notice that the topics have been created automatically from the AsyncAPI definition specified in the provided URL.
+You will notice that the topics have been created automatically from the provided AsyncAPI definition.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-streaming-api-from-an-asyncapi-definition.md`
around lines 74 - 80, Update the wording in the Topics step by replacing the
phrase "provided URL" with a source-agnostic term such as "provided AsyncAPI
definition" (or "provided definition") so the sentence no longer assumes upload
method; find the paragraph containing "topics have been created automatically
from the AsyncAPI definition specified in the provided URL" and change it to use
the new phrase so it matches both file upload and URL inputs.
| <tr><td>URL Mapping</td> <td><code>/notifications</code></td> </tr></table> | ||
|
|
||
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a> | ||
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a> |
There was a problem hiding this comment.
Fix probable broken screenshot path.
Line 180 uses wesocket-streaming-api-v3-add-topic-url-mapping.png; websocket is misspelled, so this link is likely broken.
🖼️ Proposed path fix
-<a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a>
+<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a>📝 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
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a> | |
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websocket-streaming-api.md`
at line 180, The image filename in the Markdown uses a typo
("wesocket-streaming-api-v3-add-topic-url-mapping.png") which likely breaks the
screenshot link; update the src and href occurrences to the correct filename
"websocket-streaming-api-v3-add-topic-url-mapping.png" in the line containing
the <a
href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png">
and the <img
src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png">
references so both link and image point to the corrected file name.
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-topics.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-topics.png" width="80%" alt="websub API Topics Page"></a> | ||
|
|
||
| <a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-delete-default-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-delete-default-topic.png" width="80%" alt="WebSub API Delete Existing Topic"></a> | ||
| 3. This default channel `_default` will have a default operation `receive__edfault`. |
There was a problem hiding this comment.
Correct the default operation name typo.
Line 84 says receive__edfault; this appears to be a typo and should be receive__default.
✏️ Proposed text fix
-3. This default channel `_default` will have a default operation `receive__edfault`.
+3. This default channel `_default` will have a default operation `receive__default`.📝 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
| 3. This default channel `_default` will have a default operation `receive__edfault`. | |
| 3. This default channel `_default` will have a default operation `receive__default`. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/docs/api-design-manage/design/create-api/create-streaming-api/create-a-websub-streaming-api.md`
at line 84, Fix the typo in the documented default operation name: change the
operation string from "receive__edfault" to "receive__default" in the sentence
that describes the default channel `_default` so it reads that the `_default`
channel has a default operation `receive__default`.
Comment on lines
+30
to
+38
| 8. Give your API's WSDL and click **OK**. You have two ways to provide the WSDL; | ||
|
|
||
| 1. Directly enter the WSDL URL which is <http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl> | ||
|
|
||
| []({{base_path}}/assets/attachments/103332601/soap-ui-project-wizard.png) | ||
|
|
||
| 2. If your SOAP API is created from a single WSDL and in published state, you can go to the Developer Portal, navigate to your API, and copy the WSDL URL from the Overview page. Please note that this generated WSDL URL will get expired in 15 minutes if the API has restricted visibility. | ||
|
|
||
| []({{base_path}}/assets/attachments/103332601/wsdl-url.png) |
There was a problem hiding this comment.
Tighten Step 8 wording and align visibility term with UI labels.
Line 30 and Line 36 have phrasing issues (“Give your API's WSDL”, “in published state”, “will get expired”), and “restricted visibility” should match the UI label (“Restricted by roles”) to reduce ambiguity.
✍️ Proposed text update
-8. Give your API's WSDL and click **OK**. You have two ways to provide the WSDL;
+8. Provide your API's WSDL URL and click **OK**. You can provide the WSDL in two ways:
- 2. If your SOAP API is created from a single WSDL and in published state, you can go to the Developer Portal, navigate to your API, and copy the WSDL URL from the Overview page. Please note that this generated WSDL URL will get expired in 15 minutes if the API has restricted visibility.
+ 2. If your SOAP API is created from a single WSDL and is in the Published state, you can copy the WSDL URL from the API **Overview** page in the Developer Portal. Note that this generated WSDL URL expires in 15 minutes when the API visibility is set to **Restricted by roles**.📝 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
| 8. Give your API's WSDL and click **OK**. You have two ways to provide the WSDL; | |
| 1. Directly enter the WSDL URL which is <http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl> | |
| []({{base_path}}/assets/attachments/103332601/soap-ui-project-wizard.png) | |
| 2. If your SOAP API is created from a single WSDL and in published state, you can go to the Developer Portal, navigate to your API, and copy the WSDL URL from the Overview page. Please note that this generated WSDL URL will get expired in 15 minutes if the API has restricted visibility. | |
| []({{base_path}}/assets/attachments/103332601/wsdl-url.png) | |
| 8. Provide your API's WSDL URL and click **OK**. You can provide the WSDL in two ways: | |
| 1. Directly enter the WSDL URL which is <http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl> | |
| []({{base_path}}/assets/attachments/103332601/soap-ui-project-wizard.png) | |
| 2. If your SOAP API is created from a single WSDL and is in the Published state, you can copy the WSDL URL from the API **Overview** page in the Developer Portal. Note that this generated WSDL URL expires in 15 minutes when the API visibility is set to **Restricted by roles**. | |
| []({{base_path}}/assets/attachments/103332601/wsdl-url.png) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/docs/api-developer-portal/invoke-apis/invoke-apis-using-tools/invoke-an-api-using-a-soap-client.md`
around lines 30 - 38, Update the wording in Step 8 to be clearer and match UI
terminology: change "Give your API's WSDL" to "Provide your API's WSDL", change
"in published state" to "published", change "will get expired" to "will expire",
and replace "restricted visibility" with the exact UI label "Restricted by
roles"; ensure the two bullets under Step 8 and any related sentences use these
revised phrases for consistency (locate the Step 8 block in the
invoke-an-api-using-a-soap-client.md content and update the sentence fragments
accordingly).
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Purpose
Add doc updates for:
Summary by CodeRabbit
Release Notes
Documentation
New Features