📝 added documentation for client generation, reformated the head… #740
Conversation
|
Greetings from Munich! 🥨 |
📝 WalkthroughWalkthroughDocumentation for OpenAPI client generation is reorganized and expanded. The section generating API definitions is renamed to "Generating OpenAPI definition," a new "Generating OpenAPI client" section is introduced with npm-based workflow and inline configuration examples, and existing endpoint documentation is redistributed throughout the document. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
github-actions
bot
added
the
Type: Documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@docs/cross-cutting-concepts/openapi.md`:
- Line 50: Remove the trailing space at the end of the sentence "All ``yaml``
files in the folder defined under `glob` will be recognised and used for
generating a client." so the line ends immediately after "client." to satisfy
markdown linting; locate the exact sentence in
docs/cross-cutting-concepts/openapi.md and delete the extra whitespace character
at the end of the line.
- Line 14: Update the sentence "The next sections provide an overview how the
documentation is integrated and explains the usage." by inserting the missing
preposition so it reads "The next sections provide an overview of how the
documentation is integrated and explains the usage." — locate that exact
sentence in docs/cross-cutting-concepts/openapi.md and make the change.
- Line 56: Replace the non-descriptive link text "here" in the sentence "This
configuration file supports limited placeholders, which are described
[here](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration)."
with a descriptive label such as "OpenAPI Generator CLI configuration
placeholders" (or similar concise phrase) so the link becomes "[OpenAPI
Generator CLI configuration
placeholders](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration)";
keep the URL unchanged and ensure the updated text reads naturally in the
sentence for accessibility/screen-reader clarity.
- Around line 58-88: The JSON example incorrectly nests the
"<<yourNameOrVersion>>" entry inside the "refarch-backend" object under
"generators"; move the "<<yourNameOrVersion>>" block out so it is a sibling of
"refarch-backend" within the "generators" object (i.e., two top-level entries
under "generators": "refarch-backend" and "<<yourNameOrVersion>>"), preserving
the inner properties ("generatorName", "glob", "output", "additionalProperties")
exactly as shown.
- Line 41: Add a single blank line immediately above the "## Generating OpenAPI
client" heading in docs/cross-cutting-concepts/openapi.md so the heading is
separated from the previous paragraph or content; update the markdown by
inserting one empty line before the "## Generating OpenAPI client" line to
satisfy markdown linting and proper rendering.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/cross-cutting-concepts/openapi.md
🧰 Additional context used
🪛 GitHub Actions: Deploy documentation website
docs/cross-cutting-concepts/openapi.md
[warning] 1-1: Code style issues found in this file. Run Prettier with --write to fix.
🪛 markdownlint-cli2 (0.18.1)
docs/cross-cutting-concepts/openapi.md
41-41: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
50-50: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
56-56: Link text should be descriptive
(MD059, descriptive-link-text)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-maven
🔇 Additional comments (3)
docs/cross-cutting-concepts/openapi.md (3)
16-16: LGTM! Better naming for clarity.The section rename from "Generating API definition" to "Generating OpenAPI definition" improves specificity and aligns with OpenAPI terminology.
90-104: LGTM! Clear documentation of available endpoints.The "Available documentation endpoints" section provides clear, accurate information about accessing the OpenAPI documentation via Swagger UI, including both the full path and shortform.
1-179: The review comment cannot be verified without additional context. The filedocs/cross-cutting-concepts/openapi.mdis currently in a clean git state with no uncommitted changes, and the JSON block appears structurally valid. However, the comment refers to a "pipeline failure" and specific "JSON structure error" and "markdown linting issues" without identifying what these issues are. The comment ends with ``, suggesting it is incomplete. To accurately address this review, please provide: (1) the specific pipeline failure logs or output, (2) the exact formatting or linting issues flagged, or (3) confirmation that issues actually exist in the current state of the file.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| - `/v3/api-docs.yaml` | ||
|
|
||
| These endpoints are normally used for client generation, validation or export of the documentation as this is a standardized format for any OpenAPI generator. | ||
| The next sections provide an overview how the documentation is integrated and explains the usage. |
There was a problem hiding this comment.
Minor grammar fix needed.
The phrase "provide an overview how" should be "provide an overview of how" for correct grammar.
📝 Proposed fix
-The next sections provide an overview how the documentation is integrated and explains the usage.
+The next sections provide an overview of how the documentation is integrated and explains the usage.📝 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.
| The next sections provide an overview how the documentation is integrated and explains the usage. | |
| The next sections provide an overview of how the documentation is integrated and explains the usage. |
🤖 Prompt for AI Agents
In `@docs/cross-cutting-concepts/openapi.md` at line 14, Update the sentence "The
next sections provide an overview how the documentation is integrated and
explains the usage." by inserting the missing preposition so it reads "The next
sections provide an overview of how the documentation is integrated and explains
the usage." — locate that exact sentence in
docs/cross-cutting-concepts/openapi.md and make the change.
| Changing the output file location or name via plugin configuration is highly discouraged, as other processes (e.g., client generation) might depend on the default. | ||
| ::: | ||
|
|
||
| ## Generating OpenAPI client |
There was a problem hiding this comment.
Add blank line above heading.
Markdown best practice requires a blank line before headings for proper rendering and linter compliance.
📝 Proposed fix
:::
+
## Generating OpenAPI client📝 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.
| ## Generating OpenAPI client | |
| ## Generating OpenAPI client |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
41-41: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
In `@docs/cross-cutting-concepts/openapi.md` at line 41, Add a single blank line
immediately above the "## Generating OpenAPI client" heading in
docs/cross-cutting-concepts/openapi.md so the heading is separated from the
previous paragraph or content; update the markdown by inserting one empty line
before the "## Generating OpenAPI client" line to satisfy markdown linting and
proper rendering.
| ``` | ||
|
|
||
| ::: info Information | ||
| All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client. |
There was a problem hiding this comment.
Remove trailing space.
Line 50 has a trailing space that should be removed per markdown linting rules.
📝 Proposed fix
-All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client.
+All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client.📝 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.
| All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client. | |
| All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client. |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
50-50: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🤖 Prompt for AI Agents
In `@docs/cross-cutting-concepts/openapi.md` at line 50, Remove the trailing space
at the end of the sentence "All ``yaml`` files in the folder defined under
`glob` will be recognised and used for generating a client." so the line ends
immediately after "client." to satisfy markdown linting; locate the exact
sentence in docs/cross-cutting-concepts/openapi.md and delete the extra
whitespace character at the end of the line.
|
|
||
| The generator is configured via the ``openapitools.json`` file. | ||
| It is possible to add further specifications and generate clients from the same config-file. | ||
| This configuration file supports limited placeholders, which are described [here](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration). |
There was a problem hiding this comment.
Use descriptive link text instead of "here".
The link text "here" is not descriptive. Screen readers and accessibility tools benefit from meaningful link text.
📝 Proposed fix
-This configuration file supports limited placeholders, which are described [here](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration).
+This configuration file supports limited placeholders, which are described in the [OpenAPI Generator CLI configuration documentation](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration).📝 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.
| This configuration file supports limited placeholders, which are described [here](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration). | |
| This configuration file supports limited placeholders, which are described in the [OpenAPI Generator CLI configuration documentation](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration). |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
56-56: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
In `@docs/cross-cutting-concepts/openapi.md` at line 56, Replace the
non-descriptive link text "here" in the sentence "This configuration file
supports limited placeholders, which are described
[here](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration)."
with a descriptive label such as "OpenAPI Generator CLI configuration
placeholders" (or similar concise phrase) so the link becomes "[OpenAPI
Generator CLI configuration
placeholders](https://github.com/OpenAPITools/openapi-generator-cli?tab=readme-ov-file#configuration)";
keep the URL unchanged and ensure the updated text reads naturally in the
sentence for accessibility/screen-reader clarity.
| ```json | ||
| { | ||
| "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json", | ||
| "spaces": 2, | ||
| "generator-cli": { | ||
| "version": "7.13.0", | ||
| "generators": { | ||
| "refarch-backend": { | ||
| "generatorName": "typescript-fetch", | ||
| "glob": "../refarch-backend/target/*.yaml", | ||
| "output": "#{cwd}/src/api/#{name}", | ||
| "additionalProperties": { | ||
| "supportsES6": true, | ||
| "enumPropertyNaming": "UPPERCASE", | ||
| "typescriptThreePlus": true | ||
| }, | ||
| "<<yourNameOrVersion>>": { | ||
| "generatorName": "typescript-fetch", | ||
| "glob": "../specLocation/*.yaml", | ||
| "output": "#{cwd}/src/api/#{name}", | ||
| "additionalProperties": { | ||
| "supportsES6": true, | ||
| "enumPropertyNaming": "UPPERCASE", | ||
| "typescriptThreePlus": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Critical JSON structure error in configuration example.
The <<yourNameOrVersion>> entry (lines 74-83) is incorrectly nested inside the refarch-backend object. It should be a sibling entry at the same level as refarch-backend under the generators object.
The current structure has <<yourNameOrVersion>> as a property of refarch-backend, which is invalid JSON and will not work with the OpenAPI generator CLI.
🐛 Proposed fix for JSON structure
{
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "7.13.0",
"generators": {
"refarch-backend": {
"generatorName": "typescript-fetch",
"glob": "../refarch-backend/target/*.yaml",
"output": "#{cwd}/src/api/#{name}",
"additionalProperties": {
"supportsES6": true,
"enumPropertyNaming": "UPPERCASE",
"typescriptThreePlus": true
}
- "<<yourNameOrVersion>>": {
+ },
+ "<<yourNameOrVersion>>": {
"generatorName": "typescript-fetch",
"glob": "../specLocation/*.yaml",
"output": "#{cwd}/src/api/#{name}",
"additionalProperties": {
"supportsES6": true,
"enumPropertyNaming": "UPPERCASE",
"typescriptThreePlus": true
}
}
}
}
}🤖 Prompt for AI Agents
In `@docs/cross-cutting-concepts/openapi.md` around lines 58 - 88, The JSON
example incorrectly nests the "<<yourNameOrVersion>>" entry inside the
"refarch-backend" object under "generators"; move the "<<yourNameOrVersion>>"
block out so it is a sibling of "refarch-backend" within the "generators" object
(i.e., two top-level entries under "generators": "refarch-backend" and
"<<yourNameOrVersion>>"), preserving the inner properties ("generatorName",
"glob", "output", "additionalProperties") exactly as shown.
…er sequence
Pull Request
Changes
Reference
Issue: #739
Checklist
Note: If some checklist items are not relevant for your PR, just remove them.
General
I have read the Contribution Guidelines (TBD)Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.