Add REST API markdown docs based on openapi definition

Use the openapi-generator-cli to generate markdown docs from the openapi.json.
Also document how this works and add a hint that the generator supports
various doc and code languages.

documentation/OpenAPI.md

@@ -50,3 +50,24 @@ Use the `openapi-generator-cli` from the root of this repository:
 ```bash
 openapi-generator-cli generate -g typescript-axios -i ./documentation/openapi.json -o node/common/src/client/ --additional-properties=supportsES6=true,typescriptThreePlus=true --skip-validate-spec
 ```
+
+## Generate API Documentation
+
+Documentation for the service API can be generated as markdown files.
+
+If not already done for generating the typescript API, install the `openapi-generator-cli`:
+
+```bash
+npm install @openapitools/openapi-generator-cli -g
+openapi-generator-cli version-manager set 7.8.0
+```
+
+Use the `openapi-generator-cli` from the root of this repository:
+
+```bash
+openapi-generator-cli generate -g markdown -i ./documentation/openapi.json -o ./documentation/api --skip-validate-spec
+```
+
+> [!TIP]
+> The Open API generator supports generating code and documentation in various languages.
+> Execute `openapi-generator-cli list` to see all of them.

documentation/api/Apis/AppDefinitionResourceApi.md

@@ -0,0 +1,36 @@
+# AppDefinitionResourceApi
+
+All URIs are relative to *http://localhost*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**serviceAppdefinitionAppIdGet**](AppDefinitionResourceApi.md#serviceAppdefinitionAppIdGet) | **GET** /service/appdefinition/{appId} | List app definitions |
+
+
+<a name="serviceAppdefinitionAppIdGet"></a>
+# **serviceAppdefinitionAppIdGet**
+> List serviceAppdefinitionAppIdGet(appId)
+
+List app definitions
+
+    List available app definitions.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **appId** | **String**|  | [default to null] |
+
+### Return type
+
+[**List**](../Models/AppDefinitionSpec.md)
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+

documentation/api/Apis/RootResourceApi.md

@@ -0,0 +1,64 @@
+# RootResourceApi
+
+All URIs are relative to *http://localhost*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**serviceAppIdGet**](RootResourceApi.md#serviceAppIdGet) | **GET** /service/{appId} | Ping |
+| [**servicePost**](RootResourceApi.md#servicePost) | **POST** /service | Launch Session |
+
+
+<a name="serviceAppIdGet"></a>
+# **serviceAppIdGet**
+> Boolean serviceAppIdGet(appId)
+
+Ping
+
+    Replies if the service is available.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **appId** | **String**|  | [default to null] |
+
+### Return type
+
+**Boolean**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: text/plain
+
+<a name="servicePost"></a>
+# **servicePost**
+> String servicePost(LaunchRequest)
+
+Launch Session
+
+    Launches a session and creates a workspace if required. Responds with the URL of the launched session.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **LaunchRequest** | [**LaunchRequest**](../Models/LaunchRequest.md)|  | [optional] |
+
+### Return type
+
+**String**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: text/plain
+

documentation/api/Apis/SessionResourceApi.md

@@ -0,0 +1,150 @@
+# SessionResourceApi
+
+All URIs are relative to *http://localhost*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**serviceSessionAppIdUserGet**](SessionResourceApi.md#serviceSessionAppIdUserGet) | **GET** /service/session/{appId}/{user} | List sessions |
+| [**serviceSessionDelete**](SessionResourceApi.md#serviceSessionDelete) | **DELETE** /service/session | Stop session |
+| [**serviceSessionPatch**](SessionResourceApi.md#serviceSessionPatch) | **PATCH** /service/session | Report session activity |
+| [**serviceSessionPerformanceAppIdSessionNameGet**](SessionResourceApi.md#serviceSessionPerformanceAppIdSessionNameGet) | **GET** /service/session/performance/{appId}/{sessionName} | Get performance metrics |
+| [**serviceSessionPost**](SessionResourceApi.md#serviceSessionPost) | **POST** /service/session | Start a new session |
+
+
+<a name="serviceSessionAppIdUserGet"></a>
+# **serviceSessionAppIdUserGet**
+> List serviceSessionAppIdUserGet(appId, user)
+
+List sessions
+
+    List sessions of a user.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **appId** | **String**|  | [default to null] |
+| **user** | **String**|  | [default to null] |
+
+### Return type
+
+[**List**](../Models/SessionSpec.md)
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+<a name="serviceSessionDelete"></a>
+# **serviceSessionDelete**
+> Boolean serviceSessionDelete(SessionStopRequest)
+
+Stop session
+
+    Stops a session.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **SessionStopRequest** | [**SessionStopRequest**](../Models/SessionStopRequest.md)|  | [optional] |
+
+### Return type
+
+**Boolean**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: text/plain
+
+<a name="serviceSessionPatch"></a>
+# **serviceSessionPatch**
+> Boolean serviceSessionPatch(SessionActivityRequest)
+
+Report session activity
+
+    Updates the last activity timestamp for a session to monitor activity.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **SessionActivityRequest** | [**SessionActivityRequest**](../Models/SessionActivityRequest.md)|  | [optional] |
+
+### Return type
+
+**Boolean**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: text/plain
+
+<a name="serviceSessionPerformanceAppIdSessionNameGet"></a>
+# **serviceSessionPerformanceAppIdSessionNameGet**
+> SessionPerformance serviceSessionPerformanceAppIdSessionNameGet(appId, sessionName)
+
+Get performance metrics
+
+    Returns the current CPU and memory usage of the session&#39;s pod.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **appId** | **String**|  | [default to null] |
+| **sessionName** | **String**|  | [default to null] |
+
+### Return type
+
+[**SessionPerformance**](../Models/SessionPerformance.md)
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+<a name="serviceSessionPost"></a>
+# **serviceSessionPost**
+> String serviceSessionPost(SessionStartRequest)
+
+Start a new session
+
+    Starts a new session for an existing workspace and responds with the URL of the started session.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **SessionStartRequest** | [**SessionStartRequest**](../Models/SessionStartRequest.md)|  | [optional] |
+
+### Return type
+
+**String**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: text/plain
+

documentation/api/Apis/WorkspaceResourceApi.md

@@ -0,0 +1,93 @@
+# WorkspaceResourceApi
+
+All URIs are relative to *http://localhost*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| [**serviceWorkspaceAppIdUserGet**](WorkspaceResourceApi.md#serviceWorkspaceAppIdUserGet) | **GET** /service/workspace/{appId}/{user} | List workspaces |
+| [**serviceWorkspaceDelete**](WorkspaceResourceApi.md#serviceWorkspaceDelete) | **DELETE** /service/workspace | Delete workspace |
+| [**serviceWorkspacePost**](WorkspaceResourceApi.md#serviceWorkspacePost) | **POST** /service/workspace | Create workspace |
+
+
+<a name="serviceWorkspaceAppIdUserGet"></a>
+# **serviceWorkspaceAppIdUserGet**
+> List serviceWorkspaceAppIdUserGet(appId, user)
+
+List workspaces
+
+    Lists the workspaces of a user.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **appId** | **String**|  | [default to null] |
+| **user** | **String**|  | [default to null] |
+
+### Return type
+
+[**List**](../Models/UserWorkspace.md)
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+<a name="serviceWorkspaceDelete"></a>
+# **serviceWorkspaceDelete**
+> Boolean serviceWorkspaceDelete(WorkspaceDeletionRequest)
+
+Delete workspace
+
+    Deletes a workspace.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **WorkspaceDeletionRequest** | [**WorkspaceDeletionRequest**](../Models/WorkspaceDeletionRequest.md)|  | [optional] |
+
+### Return type
+
+**Boolean**
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: text/plain
+
+<a name="serviceWorkspacePost"></a>
+# **serviceWorkspacePost**
+> UserWorkspace serviceWorkspacePost(WorkspaceCreationRequest)
+
+Create workspace
+
+    Creates a new workspace for a user.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **WorkspaceCreationRequest** | [**WorkspaceCreationRequest**](../Models/WorkspaceCreationRequest.md)|  | [optional] |
+
+### Return type
+
+[**UserWorkspace**](../Models/UserWorkspace.md)
+
+### Authorization
+
+[SecurityScheme](../README.md#SecurityScheme)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: application/json
+

documentation/api/Models/ActivityTracker.md

@@ -0,0 +1,10 @@
+# ActivityTracker
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **timeoutAfter** | **Integer** |  | [optional] [default to null] |
+| **notifyAfter** | **Integer** |  | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

documentation/api/Models/AppDefinitionListRequest.md

@@ -0,0 +1,9 @@
+# AppDefinitionListRequest
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **appId** | **String** | The App Id of this Theia Cloud instance. Request without a matching Id will be denied. | [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+