Cherry pick app api doc#743
Open
tossmilestone wants to merge 2 commits into
Open
Conversation
Contributor
WalkthroughAdds a complete OpenAPI 3.0 specification for Application APIs and four localized MDX docs (index, lifecycle, management, query) that render Overview/OpenAPIPath components and surface the new API paths and schemas. ChangesApplication API Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/shared/openapis/application.v1.json (1)
90-91: ⚡ Quick winClarify the operation summary.
The summary "List Application Resources" could be misinterpreted as listing multiple applications. Since the path includes
{name}, consider a more precise summary.📝 Suggested improvement
"get": { - "summary": "List Application Resources", + "summary": "Get Application and Sub-Resources", "description": "Lists the application resource itself and its sub-resources.",🤖 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 `@docs/shared/openapis/application.v1.json` around lines 90 - 91, Update the OpenAPI operation summary to clearly indicate this endpoint targets a single application instance (path contains {name}) rather than multiple applications; replace the ambiguous "List Application Resources" summary with a precise phrase such as "List resources for an application" or "Get resources for application {name}" in the operation's "summary" field so it matches the existing "description" that refers to the application resource and its sub-resources.
🤖 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/en/apis/advanced_apis/application/management.mdx`:
- Line 15: The docs reference two undefined endpoints
'/acp/v1/kubernetes/{cluster}/namespaces/{namespace}/applications/{name}/chartpackage'
and '/acp/v1/kubernetes/{cluster}/general-namespaces' that are not present in
the OpenAPI file; either remove these paths from
docs/en/apis/advanced_apis/application/management.mdx or add corresponding path
definitions to the OpenAPI spec (application.v1.json) including operations,
parameters, and responses so they render—locate the entries by the exact path
strings in the MDX and in application.v1.json (or the generator source that
imports it) and perform the chosen action consistently for both paths.
In `@docs/en/apis/advanced_apis/application/query.mdx`:
- Line 14: Update the path parameter name to match the OpenAPI spec by replacing
the incorrect placeholder `{cluster}` with `{cluster_name}` in the route string
used to document the endpoint (the path entry string
'/acp/v1/kubernetes/{cluster}/namespaces/{namespace}/applications/{name}');
ensure the resulting path exactly matches the OpenAPI `application.v1.json`
definition so the docs renderer picks up the correct parameter name.
In `@docs/shared/openapis/application.v1.json`:
- Line 17: The OpenAPI spec mixes path parameter names "cluster_name" and
"cluster"; find every path parameter object where "name": "cluster" (and any
path templates using {cluster}) and rename them to "cluster_name", updating any
corresponding schema/$ref, examples, and path templates (e.g., change
"/.../{cluster}/..." to "/.../{cluster_name}/...") so all endpoints consistently
use "cluster_name"; ensure required:true and schema:type remain unchanged and
run the spec validation after edits.
- Around line 8-10: The OpenAPI document references the bearerAuth security
requirement but lacks a matching components.securitySchemes entry; add a
security scheme named "bearerAuth" under components.securitySchemes that defines
an HTTP bearer token scheme (type: http, scheme: bearer, bearerFormat: JWT) so
the referenced security requirement resolves and OpenAPI validation passes;
update the components section to include this new "bearerAuth" security scheme.
---
Nitpick comments:
In `@docs/shared/openapis/application.v1.json`:
- Around line 90-91: Update the OpenAPI operation summary to clearly indicate
this endpoint targets a single application instance (path contains {name})
rather than multiple applications; replace the ambiguous "List Application
Resources" summary with a precise phrase such as "List resources for an
application" or "Get resources for application {name}" in the operation's
"summary" field so it matches the existing "description" that refers to the
application resource and its sub-resources.
🪄 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: 18798d2c-be37-44ea-b59f-987e6dc3cdd4
📒 Files selected for processing (5)
docs/en/apis/advanced_apis/application/index.mdxdocs/en/apis/advanced_apis/application/lifecycle.mdxdocs/en/apis/advanced_apis/application/management.mdxdocs/en/apis/advanced_apis/application/query.mdxdocs/shared/openapis/application.v1.json
Remove the deprecated app.k8s.io/v1beta1 API reference from the application lifecycle documentation as part of the effort to clean up Kubernetes-style resource definitions. Signed-off-by: Xiaoxi He <xxhe@alauda.io>
tossmilestone
force-pushed
the
cherry-pick-app-api-doc
branch
from
11d421d to
53d4ee3
Compare
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/shared/openapis/application.v1.json (2)
8-10:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winDefine the referenced
bearerAuthsecurity scheme.Line 8 references
bearerAuth, but there is no matchingcomponents.securitySchemes.bearerAuthdefinition, so OpenAPI validation will fail.🔧 Minimal fix
"components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } + }, "schemas": {#!/bin/bash # Verify security requirement has a matching scheme definition rg -n '"security"\s*:\s*\[' docs/shared/openapis/application.v1.json rg -n '"bearerAuth"' docs/shared/openapis/application.v1.json rg -n '"securitySchemes"\s*:' docs/shared/openapis/application.v1.jsonAlso applies to: 482-483
🤖 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 `@docs/shared/openapis/application.v1.json` around lines 8 - 10, The OpenAPI file uses the security requirement "bearerAuth" but no matching components.securitySchemes.bearerAuth is defined; add a components.securitySchemes object and define bearerAuth (e.g., type: http, scheme: bearer, bearerFormat: JWT) so the referenced "bearerAuth" under "security" resolves correctly; update the top-level schema (components → securitySchemes → bearerAuth) to match the expected name "bearerAuth" used in the "security" arrays.
231-235:⚠️ Potential issue | 🟠 Major | ⚡ Quick winStandardize
clusterpath parameter naming withcluster_name.Several endpoints still use
{cluster}/"name": "cluster"while most of this spec usescluster_name(e.g., Line 12 and peers). This inconsistency increases client/doc confusion.🔧 Example of the required normalization
- "/acp/v1/kubernetes/{cluster}/topology/{namespace}/{kind}/{name}": { + "/acp/v1/kubernetes/{cluster_name}/topology/{namespace}/{kind}/{name}": { ... - { "name": "cluster", "in": "path", "required": true, "schema": { "type": "string" } }, + { "name": "cluster_name", "in": "path", "required": true, "schema": { "type": "string" } },#!/bin/bash # List remaining mixed cluster placeholders/params for normalization rg -n '\{cluster\}' docs/shared/openapis/application.v1.json rg -n '"name":\s*"cluster"' docs/shared/openapis/application.v1.json rg -n '\{cluster_name\}' docs/shared/openapis/application.v1.json rg -n '"name":\s*"cluster_name"' docs/shared/openapis/application.v1.jsonAlso applies to: 259-263, 310-314, 331-335, 359-363, 396-403
🤖 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 `@docs/shared/openapis/application.v1.json` around lines 231 - 235, The OpenAPI spec uses the path "/acp/v1/kubernetes/{cluster}/topology/{namespace}/{kind}/{name}" and a path parameter with "name": "cluster"; standardize this to "cluster_name" everywhere: rename the path placeholder to "{cluster_name}" and update the corresponding parameter object from "name": "cluster" to "name": "cluster_name" (and any "schema" or examples referencing it) so they match the rest of the spec; apply the same replacement to the other listed endpoint occurrences (lines referenced in the review) and ensure any $ref, examples, or server/operation-level parameters that reference "cluster" are updated to "cluster_name" as well to keep the spec consistent.
🤖 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.
Duplicate comments:
In `@docs/shared/openapis/application.v1.json`:
- Around line 8-10: The OpenAPI file uses the security requirement "bearerAuth"
but no matching components.securitySchemes.bearerAuth is defined; add a
components.securitySchemes object and define bearerAuth (e.g., type: http,
scheme: bearer, bearerFormat: JWT) so the referenced "bearerAuth" under
"security" resolves correctly; update the top-level schema (components →
securitySchemes → bearerAuth) to match the expected name "bearerAuth" used in
the "security" arrays.
- Around line 231-235: The OpenAPI spec uses the path
"/acp/v1/kubernetes/{cluster}/topology/{namespace}/{kind}/{name}" and a path
parameter with "name": "cluster"; standardize this to "cluster_name" everywhere:
rename the path placeholder to "{cluster_name}" and update the corresponding
parameter object from "name": "cluster" to "name": "cluster_name" (and any
"schema" or examples referencing it) so they match the rest of the spec; apply
the same replacement to the other listed endpoint occurrences (lines referenced
in the review) and ensure any $ref, examples, or server/operation-level
parameters that reference "cluster" are updated to "cluster_name" as well to
keep the spec consistent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ad3b0119-2f6a-40a4-9844-cd2e8446f42b
📒 Files selected for processing (2)
docs/en/apis/advanced_apis/application/lifecycle.mdxdocs/shared/openapis/application.v1.json
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/en/apis/advanced_apis/application/lifecycle.mdx
Deploying alauda-container-platform with
|
| Latest commit: |
53d4ee3
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://30a989a3.alauda-container-platform.pages.dev |
| Branch Preview URL: | https://cherry-pick-app-api-doc.alauda-container-platform.pages.dev |
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.
Summary by CodeRabbit