docs: enhance openapi spec docs and cleanup script by tacklequestions · Pull Request #9 · apolloconfig/apollo-openapi

tacklequestions · 2025-09-27T09:43:48Z

Summary by CodeRabbit

New Features
- API endpoints now support environment-scoped routing and an env parameter for addressing resources by environment.
Refactor
- Public schemas consolidated and renamed to a consistent Open*-prefixed set; many responses and requests updated to use these new schemas.
- Map-of-strings representation standardized to a simple string map format.
Documentation
- Endpoint descriptions expanded and clarified to reflect environment context and parameter changes.
Chores
- Project generation adds an automated cleanup step to prune files and normalize formatting.

coderabbitai · 2025-09-27T09:43:55Z

Walkthrough

Renames and consolidates OpenAPI schemas to Open*-prefixed types, updates $ref usages and map representation to additionalProperties:string, and adds env-scoped route/parameter changes in the API. Adds a cleanup block to generate.sh that prunes files, normalizes line endings, trims trailing spaces, and ensures final newlines.

Changes

Cohort / File(s)	Summary of changes
OpenAPI schema refactor & path/param updates `apollo-openapi.yaml`	Renamed many component schemas to `Open*` variants and updated all corresponding `$ref` usages; replaced `MapString` keyed-map with `additionalProperties: string`; expanded/HTML-wrapped endpoint descriptions; introduced `env`-scoped paths and adjusted parameter schemas.
Generation script cleanup `generate.sh`	Inserted a cleanup block after adding Maven Wrapper: prints cleaning message, removes common build/VCS artifacts, targets specific file types, normalizes CRLFs, strips trailing spaces, ensures final newline, then returns to parent dir and prints readiness.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

I twitch my ears at Open* names anew,
Hops through env-scoped paths with purpose true.
Maps whisper strings in tidy lines,
The script sweeps crumbs and trims the fines.
A rabbit's cheer — merge when you do. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly identifies the two primary areas of this pull request by noting enhancements to the OpenAPI specification documentation and updates to the cleanup script, which aligns directly with the main changes introduced in the diff.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e136b4a and 48038f2.

📒 Files selected for processing (1)

generate.sh (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

generate.sh

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.

❤️ Share

🧪 Early access (Sonnet 4.5): enabled

We are currently testing the Sonnet 4.5 model, which is expected to improve code review quality. However, this model may lead to increased noise levels in the review comments. Please disable the early access features if the noise level causes any inconvenience.

Note:

Public repositories are always opted into early access features.
You can enable or disable early access features from the CodeRabbit UI or by updating the CodeRabbit configuration file.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b202f92 and 0545d86.

📒 Files selected for processing (2)

apollo-openapi.yaml (72 hunks)
generate.sh (1 hunks)

generate.sh

arrow1991 · 2025-09-27T10:13:08Z

apollo-openapi.yaml

              example:
                message: 'App not found'
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}:
+  /openapi/v1/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}:


Incompatible changes may affect users' ability to interface with OpenAPI interfaces

Already fixed that issue, thanks for reviewing!

arrow1991 · 2025-09-27T10:15:49Z

generate.sh

+find . -type d \( -name .git -o -name .idea -o -name .mvn -o -name target -o -name build -o -name node_modules \) -prune -o \
+  -type f \( -name "*.java" -o -name "*.xml" -o -name "*.properties" -o -name "*.md" -o -name "*.yml" -o -name "*.yaml" -o -name "*.sh" -o -name ".editorconfig" -o -name ".gitignore" -o -name "mvnw" -o -name "mvnw.cmd" \) -print0 \
+| xargs -0 perl -i -0777 -pe 's/[ \t]+(?=\r?$)//mg; s/\r//g; s/\s*\z/\n/s'
+echo "Done."


avoid ambiguity, for example "Cleaning files (trailing spaces, CRLF, EOF newlines) Done".

Already fixed that issue, thanks for reviewing!

arrow1991 · 2025-09-27T12:33:56Z

apollo-openapi.yaml

        dataChangeCreatedTime:
          type: string
-          description: ''
+          description: 数据创建时间（ISO 8601）


Suggest adding examples to illustrate

Already fixed that issue, thanks for reviewing!

arrow1991 · 2025-09-27T12:57:00Z

apollo-openapi.yaml

              example:
                message: 'Branch not found'
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:compare:
+  /openapi/v1/namespaces/items:compare:


When handling non-standard CRUD operations, it is recommended to consider the operation itself as a resource. For example, changing "/items:compare" to "/items/compare"

Already fixed that issue, thanks for reviewing

…oblems Co-authored-by: arrow2020 <316166287@qq.com>

docs: enhance openapi spec docs and cleanup script

0545d86

coderabbitai bot reviewed Sep 27, 2025

View reviewed changes

generate.sh Show resolved Hide resolved

arrow1991 reviewed Sep 27, 2025

View reviewed changes

fix: thoroughly checked apollo-openapi.yaml to ensure there are no pr…

48038f2

…oblems Co-authored-by: arrow2020 <316166287@qq.com>

tacklequestions force-pushed the feature/openapi-doc-update branch from e136b4a to 48038f2 Compare September 30, 2025 10:20

hezhangjian approved these changes Oct 1, 2025

View reviewed changes

hezhangjian merged commit 2d7db40 into apolloconfig:main Oct 1, 2025
3 of 4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: enhance openapi spec docs and cleanup script#9

docs: enhance openapi spec docs and cleanup script#9
hezhangjian merged 2 commits intoapolloconfig:mainfrom
tacklequestions:feature/openapi-doc-update

tacklequestions commented Sep 27, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Sep 27, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

arrow1991 Sep 27, 2025

Uh oh!

tacklequestions Sep 30, 2025

Uh oh!

arrow1991 Sep 27, 2025

Uh oh!

tacklequestions Sep 30, 2025

Uh oh!

arrow1991 Sep 27, 2025

Uh oh!

tacklequestions Sep 30, 2025

Uh oh!

arrow1991 Sep 27, 2025

Uh oh!

tacklequestions Sep 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tacklequestions commented Sep 27, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tacklequestions commented Sep 27, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Sep 27, 2025 •

edited

Loading