Fix stale generated REST API docs and add event-gateway doc generation - #3174
Conversation
|
Warning Review limit reached
Next review available in: 27 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe pull request adds Event Gateway API documentation and generation support. It updates gateway credential handling, authentication roles, HTTPS examples, response formatting, platform API-key scopes, API Portal terminology, and MCP introspection rules. ChangesREST API documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ 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: 6
🧹 Nitpick comments (1)
event-gateway/gateway-controller/Makefile (1)
50-50: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPin and isolate the
widdershinstool.
generate-apidocsaccepts any globally installedwiddershinsand installs the unresolved latest package globally when it is missing. This can change generated Markdown without a source change and can fail when the environment lacks global npm write access. Add a pinnedwiddershinsdevelopment dependency with a lockfile, and invoke the local tool instead of the global command.🤖 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 `@event-gateway/gateway-controller/Makefile` at line 50, Update the generate-apidocs target in the Makefile to invoke a repository-local widdershins binary rather than checking for or installing a global command. Add widdershins as a pinned development dependency and commit the corresponding lockfile so the tool version and transitive dependencies are reproducible.
🤖 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 `@docs/rest-apis/event-gateway/schemas.md`:
- Around line 224-233: Update the OpenAPI definition for APIKeyUpdateRequest to
declare the name field used by its example and the WebSub and WebBroker update
requests, then regenerate the REST API documentation so the Properties section
lists name instead of None.
- Around line 76-78: Update the source OpenAPI description for expiresAt to
document that omitting both expiration fields creates a non-expiring key with
expiresAt: null, and explicitly state that expiresAt takes precedence when both
expiresIn and expiresAt are supplied. Regenerate the REST API schema
documentation so the corresponding expiresAt entries are updated consistently.
- Around line 1055-1062: Update the WebSubAPIRequest schema documentation source
so WebhookAPIData.channels uses the documented array shape of {name, method}
entries, or a dedicated WebSub-specific channel schema, instead of an object
keyed by channel name. Regenerate the Markdown schema output and ensure
WebSubAPIRequest.spec references the corrected channels definition.
In `@docs/rest-apis/platform-api/schemas.md`:
- Line 5084: Update the MCP introspection example around the request containing
url, proxyId, and auth so it no longer sends auth alongside proxyId. Show either
the initial url-plus-auth flow without proxyId or the proxyId flow without auth,
consistent with the documented constraint.
- Line 2184: Update the UpdateAPIKeyRequest documentation near expiresAt to
describe update semantics: expiresAt or expiresIn sets a new expiration, while
omitting expiration preserves the existing value; specify the explicit value or
call required to remove an existing expiration.
In `@event-gateway/gateway-controller/Makefile`:
- Around line 52-57: Update the documentation generation recipe around
widdershins and split-openapi.sh to create a unique temporary file with mktemp,
pass that path to both commands, and register an EXIT trap to remove it.
Eliminate the fixed /tmp/eventgateway-openapi.md path and explicit cleanup so
concurrent runs cannot collide.
---
Nitpick comments:
In `@event-gateway/gateway-controller/Makefile`:
- Line 50: Update the generate-apidocs target in the Makefile to invoke a
repository-local widdershins binary rather than checking for or installing a
global command. Add widdershins as a pinned development dependency and commit
the corresponding lockfile so the tool version and transitive dependencies are
reproducible.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 90ab9e24-26b8-49ff-87e0-3903227345bd
📒 Files selected for processing (21)
docs/rest-apis/event-gateway/README.mddocs/rest-apis/event-gateway/authentication.mddocs/rest-apis/event-gateway/schemas.mddocs/rest-apis/event-gateway/webbroker-api-management.mddocs/rest-apis/event-gateway/websub-api-management.mddocs/rest-apis/gateway/certificate-management.mddocs/rest-apis/gateway/llm-provider-management.mddocs/rest-apis/gateway/llm-provider-template-management.mddocs/rest-apis/gateway/llm-proxy-management.mddocs/rest-apis/gateway/mcp-proxy-management.mddocs/rest-apis/gateway/rest-api-management.mddocs/rest-apis/gateway/schemas.mddocs/rest-apis/gateway/secrets-management.mddocs/rest-apis/platform-api/README.mddocs/rest-apis/platform-api/api-keys.mddocs/rest-apis/platform-api/applications.mddocs/rest-apis/platform-api/llm-providers.mddocs/rest-apis/platform-api/llm-proxies.mddocs/rest-apis/platform-api/rest-apis.mddocs/rest-apis/platform-api/schemas.mdevent-gateway/gateway-controller/Makefile
3d3bc3f to
31b5c11
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
event-gateway/gateway-controller/Makefile (1)
50-50: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPin and manage the Widdershins version.
Line 50 accepts any existing
widdershinsbinary. Otherwise, it installs an unpinned global package. Different environments can therefore generate different Markdown from the same OpenAPI specification. Add Widdershins as a locked development dependency and invoke that binary, or install an explicitly approved version.🤖 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 `@event-gateway/gateway-controller/Makefile` at line 50, Update the Makefile target around the widdershins invocation to use a pinned, project-managed Widdershins development dependency and invoke its local binary instead of accepting any system executable or installing an unpinned global package. Ensure the dependency version is locked in the project manifest and lockfile.
🤖 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 `@docs/rest-apis/platform-api/schemas.md`:
- Line 5078: Resolve the duplicate “Properties” heading in the generated schema
documentation by assigning that section a unique heading, or update the
markdownlint MD024 configuration for this generated format. Preserve the
surrounding schema documentation structure and ensure markdownlint passes.
In `@event-gateway/gateway-controller/Makefile`:
- Line 55: Update the generate-apidocs target’s widdershins input path to derive
from REPO_ROOT and point to
event-gateway/gateway-controller/api/eventgateway-openapi.yaml, so the target
works when invoked from the repository root or another working directory.
- Around line 58-59: Quote the path arguments in the Makefile command: wrap the
template-directory expression in the widdershins invocation, the splitter script
path, and DOCS_OUT_DIR in double quotes so checkout paths containing whitespace
remain single shell arguments.
---
Nitpick comments:
In `@event-gateway/gateway-controller/Makefile`:
- Line 50: Update the Makefile target around the widdershins invocation to use a
pinned, project-managed Widdershins development dependency and invoke its local
binary instead of accepting any system executable or installing an unpinned
global package. Ensure the dependency version is locked in the project manifest
and lockfile.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: b08ec2eb-8832-4bc7-82fb-d7e713fab2c6
📒 Files selected for processing (2)
docs/rest-apis/platform-api/schemas.mdevent-gateway/gateway-controller/Makefile
2 participants
Purpose
Regenerates the gateway REST API docs, which had drifted from the spec:
admin, developer; the spec restricts them toadmin.upstream.auth.valuenot marked write-only despitewriteOnly: true, so response examples leaked a credential placeholder.Adds a
generate-apidocstarget to event-gateway/gateway-controller, mirroring the platform-api one. WebSub and WebBroker docs previously had no generator and were kept as hand-copied files under docs/rest-apis/gateway/; those are removed in favour of generated output in docs/rest-apis/event-gateway/.Also documents that an omitted
expiresAtmeans the API key never expires (platform-api/resources/openapi.yaml), matching apikey.go.