Fix documentation updates#11393
Open
PabasaraIlankoon wants to merge 1 commit into
Open
Conversation
PabasaraIlankoon
requested review from
chamilaadhi and
tharikaGitHub
as code owners
|
|
📝 WalkthroughDocumentation Updates for API Gateway and Dev Portal GuidesThis PR fixes documentation inconsistencies and improves clarity across API Manager guides: API Gateway Configuration Guides
Dev Portal Publishing Guides
All changes improve documentation accuracy and consistency with minimal impact. No code alterations, security concerns, or breaking changes. WalkthroughThis pull request contains documentation updates across six API Manager guide files. The changes include fixing admonition directive capitalization, correcting an SSI-to-SSL typo in debug logging instructions, updating deprecated cache mediator links to current EI 6.5.0 documentation, converting hardcoded URLs to site-relative references, generalizing cache invalidation monitoring guidance to include the MI monitoring dashboard, removing a trailing parenthesis from an AWS CLI URL, and adding an outdated content warning for gateway scaling documentation with updated throttling policy guidance and spelling corrections. Suggested reviewers
🚥 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: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/response-caching.md`:
- Line 82: Remove the draft placeholder and fix grammar: replace the sentence
with a clear statement such as "You can invalidate all cached responses remotely
by using the exposed MBeans at
{{base_path}}/observe/mi-observe/mi-monitoring-dashboard or by invoking the
InvalidateMediatorCache() operation of the org.wso2.carbon.mediation MBean."
Ensure "cached response" is pluralized to "cached responses" and the editing
instruction "Update to APIM-relevant monitoring docs or use" is removed;
reference the MBean operation InvalidateMediatorCache() and the dashboard path
to locate the content to edit.
- Line 3: Remove the draft instruction phrase "Update to current EI 6.5.0 docs
URL or note it as a legacy reference" from the sentence containing "The API
Manager uses Update to current EI 6.5.0 docs URL or note it as a legacy
reference to cache response messages for each API" and replace it with a clear
description of the caching component (e.g., "The API Manager uses the Response
Cache mediator to cache response messages for each API"), keeping the remainder
of the sentence about performance and the need to set an appropriate timeout
period to avoid stale data.
In
`@en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/scaling-the-gateway.md`:
- Line 5: Replace the inline text "Note: per GitHub issue `#8379`, this section is
outdated for 4.x and should be removed or updated" with either an
updated/removed section or a proper MkDocs admonition; if keeping temporarily,
wrap the specific scope in a warning admonition (e.g., use "!!! warning
\"Outdated Content for API Manager 4.x\"" and clearly state which lines or
subsection are outdated and link GitHub issue `#8379`), or fully update the
surrounding content to be accurate for 4.x or remove it entirely so the page no
longer contains ambiguous inline notes.
🪄 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: f34048b7-a97a-4ed7-b9d2-90eaad22a482
📒 Files selected for processing (6)
en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/message-tracing.mden/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/mutual-ssl-between-api-gateway-and-backend.mden/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/response-caching.mden/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/scaling-the-gateway.mden/docs/api-design-manage/deploy-and-publish/publish-on-dev-portal/publish-an-api.mden/docs/api-design-manage/deploy-and-publish/publish-on-dev-portal/publish-aws-apis-in-the-dev-portal.md
| #Response caching | ||
|
|
||
| The API Manager uses [WSO2 ESB's cache mediator](https://docs.wso2.com/display/EI650/Cache+Mediator) to cache response messages for each API. Caching improves performance, because the backend server does not have to process the same data for a request multiple times. You need to set an appropriate timeout period to offset the risk of stale data in the cache. | ||
| The API Manager uses Update to current EI 6.5.0 docs URL or note it as a legacy reference to cache response messages for each API. Caching improves performance, because the backend server does not have to process the same data for a request multiple times. You need to set an appropriate timeout period to offset the risk of stale data in the cache. |
There was a problem hiding this comment.
Draft text accidentally left in the documentation.
Line 3 contains editing instructions that should have been removed: "Update to current EI 6.5.0 docs URL or note it as a legacy reference". This makes the sentence incomprehensible.
The text should describe what component is used for caching, not include instructions for updating the documentation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/response-caching.md`
at line 3, Remove the draft instruction phrase "Update to current EI 6.5.0 docs
URL or note it as a legacy reference" from the sentence containing "The API
Manager uses Update to current EI 6.5.0 docs URL or note it as a legacy
reference to cache response messages for each API" and replace it with a clear
description of the caching component (e.g., "The API Manager uses the Response
Cache mediator to cache response messages for each API"), keeping the remainder
of the sentence about performance and the need to set an appropriate timeout
period to avoid stale data.
| ## Invalidating Cached Responses Remotely | ||
|
|
||
| You can invalidate all cached response remotely by using any [JMX monitoring tool such as Jconsole](https://ei.docs.wso2.com/en/latest/micro-integrator/administer-and-observe/jmx_monitoring) using the exposed MBeans. You can use the `InvalidateMediatorCache()` operation of the `org.wso2.carbon.mediation` MBean for this as shown below. | ||
| You can invalidate all cached response remotely by using any Update to APIM-relevant monitoring docs or use {{base_path}}/observe/mi-observe/mi-monitoring-dashboard using the exposed MBeans. You can use the `InvalidateMediatorCache()` operation of the `org.wso2.carbon.mediation` MBean for this as shown below. |
There was a problem hiding this comment.
Draft text and grammar issue in documentation.
Line 82 contains draft editing instructions that should have been removed: "Update to APIM-relevant monitoring docs or use". Additionally, "cached response" should be "cached responses" (plural).
The sentence should clearly describe the tools or methods available for cache invalidation, not include editing placeholders.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/response-caching.md`
at line 82, Remove the draft placeholder and fix grammar: replace the sentence
with a clear statement such as "You can invalidate all cached responses remotely
by using the exposed MBeans at
{{base_path}}/observe/mi-observe/mi-monitoring-dashboard or by invoking the
InvalidateMediatorCache() operation of the org.wso2.carbon.mediation MBean."
Ensure "cached response" is pluralized to "cached responses" and the editing
instruction "Update to APIM-relevant monitoring docs or use" is removed;
reference the MBean operation InvalidateMediatorCache() and the dashboard path
to locate the content to edit.
| Scaling the Gateway requires considering the load that the Gateways will handle. We recommend that a load test be carried out on the Gateways in the environment. For more information on what factors affect the load, and how the numbers have to be derived in order to scale, refer to the article on [Capacity Planning](https://wso2.com/library/articles/2015/12/article-capacity-planning-exercise-with-wso2-middleware-platform/) . Make sure to check the backends as well for the expected load. | ||
|
|
||
| ### Clustering Gateways and Key Managers with key caching | ||
| Note: per GitHub issue #8379, this section is outdated for 4.x and should be removed or updated |
There was a problem hiding this comment.
Use proper admonition syntax and update outdated content instead of flagging it.
The inline note has several issues:
- It does not use standard MkDocs admonition syntax (e.g.,
!!! warningor!!! note). - "this section" is ambiguous—it's unclear which specific content is outdated.
- If content is confirmed outdated for 4.x versions, update or remove it rather than leaving it in place with an inline warning that confuses readers.
📝 Suggested approach
Either:
- Update the outdated content to be accurate for 4.x, or
- Remove the outdated content entirely, or
- If the content must remain temporarily, use a proper warning admonition with specific scope:
!!! warning "Outdated Content for API Manager 4.x"
The following guidance on key validation performance (lines 7-13) is outdated for APIM 4.x. See [GitHub issue `#8379`](https://github.com/wso2/docs-apim/issues/8379) for updates.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/docs/api-design-manage/deploy-and-publish/deploy-on-gateway/api-gateway/scaling-the-gateway.md`
at line 5, Replace the inline text "Note: per GitHub issue `#8379`, this section
is outdated for 4.x and should be removed or updated" with either an
updated/removed section or a proper MkDocs admonition; if keeping temporarily,
wrap the specific scope in a warning admonition (e.g., use "!!! warning
\"Outdated Content for API Manager 4.x\"" and clearly state which lines or
subsection are outdated and link GitHub issue `#8379`), or fully update the
surrounding content to be accurate for 4.x or remove it entirely so the page no
longer contains ambiguous inline notes.
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
2 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.
Purpose
Goals
Approach
User stories
Release note
Documentation
Training
Certification
Marketing
Automation tests
N/A (documentation-only change)
Security checks
Samples
Related PRs
Migrations (if applicable)
Test environment
Learning