Skip to content

📝 added documentation for client generation, reformated the head… #740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
langehm wants to merge 1 commit into
base: main
Choose a base branch
from
Open

📝 added documentation for client generation, reformated the head… #740

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 69 additions & 20 deletions docs/cross-cutting-concepts/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,16 @@ The documentation of the API (at least the [backend template](../templates/getti
The OpenAPI definition is generated by scanning the Spring `@Controller`'s, which serve as the Single Source of Truth.
Thus, the documentation of the API is not saved anywhere permanent inside the codebase and generated on-the-fly only.

The next sections provide an overview how the documentation is integrated and explains the usage.

## Available documentation endpoints

The OpenAPI documentation is exposed via two endpoints explained below.
Both endpoints will be dynamically updated based on the current annotations and Javadoc present in the `@Controller` code.

### Swagger UI

The [Swagger UI](https://swagger.io/tools/swagger-ui/) provides a web-based interface for exploring and testing the documented API.
It is automatically available when using `springdoc-openapi-starter-webmvc-ui` (which is included in the backend template by default) and can be accessed via the following path:

- `/swagger-ui/index.html` or
- `/swagger-ui` (shortform)

This endpoint renders the OpenAPI specification in a user-friendly format and allows direct interaction with all available endpoints.

### OpenAPI

The raw OpenAPI specification is served as machine-readable `.json` and `.yaml`.
It can be retrieved from the following standard paths:

- `/v3/api-docs` (`.json`) or
- `/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.
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
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.


## Generating API definition
## Generating OpenAPI definition

The current API definition can be generated locally as a `.yaml` file using the [Springdoc Maven plugin](https://springdoc.org/#maven-plugin).

Expand All @@ -56,6 +38,71 @@ The OpenAPI `.yaml` file will be saved to the project's target directory with th
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
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
## 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.

The previously generated OpenAPI specification can be used to automatically generate type-safe API clients.
This is performed via the ``@openapitools/openapi-generator-cli`` and the following npm command:

```shell
npm run api-gen
```

::: info Information
All ``yaml`` files in the folder defined under `glob` will be recognised and used for generating a client.
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
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.

Each will have its own destination folder.
:::

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).
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
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
}
}
}
}
}
}
```
Comment on lines +58 to +88
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

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.


## Available documentation endpoints

The OpenAPI documentation is exposed via two endpoints explained below.
Both endpoints will be dynamically updated based on the current annotations and Javadoc present in the `@Controller` code.

### Swagger UI

The [Swagger UI](https://swagger.io/tools/swagger-ui/) provides a web-based interface for exploring and testing the documented API.
It is automatically available when using `springdoc-openapi-starter-webmvc-ui` (which is included in the backend template by default) and can be accessed via the following path:

- `/swagger-ui/index.html` or
- `/swagger-ui` (shortform)

This endpoint renders the OpenAPI specification in a user-friendly format and allows direct interaction with all available endpoints.


## Documenting endpoints

Currently, there are two ways to add documentation to an endpoint. Those will be further explained below.
Expand Down Expand Up @@ -129,3 +176,5 @@ public SomeEntity getEndpoint(@PathVariable("someId") final UUID someId) {
return service.doSth(someId);
}
```


Loading