From 768487609500f4f1803c3a462939cbea3e900047 Mon Sep 17 00:00:00 2001
From: langehm <38280183+langehm@users.noreply.github.com>
Date: Fri, 16 Jan 2026 11:16:32 +0100
Subject: [PATCH] :memo: added documentation for client generation, reformated
 the header sequence

---
 docs/cross-cutting-concepts/openapi.md | 89 ++++++++++++++++++++------
 1 file changed, 69 insertions(+), 20 deletions(-)

diff --git a/docs/cross-cutting-concepts/openapi.md b/docs/cross-cutting-concepts/openapi.md
index 4d1912d3..0862fef0 100644
--- a/docs/cross-cutting-concepts/openapi.md
+++ b/docs/cross-cutting-concepts/openapi.md
@@ -4,25 +4,6 @@ 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:
 
@@ -30,8 +11,9 @@ It can be retrieved from the following standard paths:
 - `/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.
 
-## 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).
 
@@ -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
+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. 
+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).
+
+```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
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 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.
@@ -129,3 +176,5 @@ public SomeEntity getEndpoint(@PathVariable("someId") final UUID someId) {
   return service.doSth(someId);
 }
 ```
+
+