[JS] Add documentation for setting custom base path (v4) (#1975)

* chore: add documentation for setting custom base path

* Revert "chore: add documentation for setting custom base path"

This reverts commit c6af354.

* chore: add documentation for setting custom base path in v4

* fix: prettier

* chore: address review comments

* chore: address review comments

docs-js/features/openapi/execute-openapi-request.mdx

@@ -114,6 +114,18 @@ MyEntity.requestBuilder()
 
 <CustomRequestConfigNote />
 
+### Setting a Custom Service Path
+
+A custom service path can be manually set in the `options-per-service.json` by providing a `basePath` property during client generation.
+It can also be adjusted per request by using the `setBasePath()` method:
+
+```ts
+MyApi.myFunction().setBasePath('/base/path/to/service').execute(destination);
+```
+
+This will change the base path of the request.
+Executing the example request above against a destination with the URL `https://my.some-system.com` will result in a request against the target like this: `https://my.some-system.com/base/path/to/service/myFunctionPath`, where `/myFunctionPath` is the API path parameter.
+
 ### Setting Middlewares
 
 You can specify middlewares for a request via the `middleware()` method on the request builder:

docs-js/features/openapi/generate-openapi-client.mdx

@@ -41,6 +41,32 @@ npx openapi-generator --input <input> --outputDir <outputDirectory>
 
 The `<input>` points to your specification file or a directory containing the specification(s) and `<outputDirectory>` to the target folder where the generated client(s) will be saved.
 
+An `options-per-service.json` file is created using the `--optionsPerService` option.
+
+- When set to a directory path, an `options-per-service.json` file is read from or created in the given directory.
+- When set to a file path, the file is read or created with the given name.
+
+This file is used for customizing subdirectory naming and contains a mapping from the original file name to the following information:
+
+- `directoryName`: the name of the subdirectory the client code will be generated into.
+- `packageName`: the name of the npm package, if a package.json file is generated.
+  This information is optional.
+- `basePath`: the URL path to be prepended to the API path before every request.
+
+This information can be adjusted manually and ensures that every run of the generator produces the same names for the generation.
+
+Example:
+
+```json
+{
+  "path/to/your/service-specifications/MyService.yaml": {
+    "directoryName": "my-service",
+    "basePath": "/base/path/to/service",
+    "packageName": "my-service"
+  }
+}
+```
+
 By default, the generated clients will each contain:
 
 - API files as `.ts` files - one for each "API" in the service.