feat: Adding Cloud Events to Miranum API docs (#19)

* Feat: Adding Cloud Events to our API Docu

* Fix: Incorporate feedback from PR

* feat: update cloud-events docu generation process in readme

Author: Hafflgav

README.md

@@ -24,11 +24,41 @@ We also want to ensure a unified naming of our product components. Hence, please
 ### Local Development 
 `npm run start`
 
-### Troubleshooting checklist
+### Troubleshooting Checklist
 Have you pulled latest from `main`?
 Have you run npm install? When we update dependencies in the project, they don't automatically get updated in your environment.
 You'll need to run npm install occasionally to acquire dependency updates locally.
 
+### Cloud Events Documentation
+We generate the cloud events documentation from the `schema.json` files stored in the [static folder](./docs/apis/static/schemas). 
+For that purpose we use the [Docusaurus-JSON-Schema-Plugin](https://jy95.github.io/docusaurus-json-schema-plugin/). If you want to 
+update a schema file you simply need to replace the outdated one. In case you want to add a new one, make sure to to create a new 
+`.mdx` file in the [cloud-events](./docs/apis/cloud-events) folder of the API documentation besides of adding the `schema.json`.
+Import the new schema and add import the Docusaurus-JSON-Schema-Plugin via: 
+
+```
+import Schema from "../../static/schemas/bpmn/command/xyz.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# <CommandName>
+<JSONSchemaViewer schema={ Schema } />
+
+# Source: 
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>
+```
+
+### Creating new files 
+If you have created a new file for the documentation you always need to make sure that it contains a proper header: 
+```
+---
+id: cloud-events-overview
+title: Cloud Events Overview
+sidebar_label: Overview
+description: "This section provides an overview of the different Cloud Event commands which are supported by Miranum Connect."
+---
+```
+If the page should show up in the sidebar it needs to be added to the [sidebar.js](./sidebars.js). By default, this should always be the case. 
+
 ## Configuration
 This documentation is built using [Docusaurus 2](https://docusaurus.io), a modern static website generator.
 The framework is well documented and is used by many (open source) projects.

docs/apis/api-overview.md

@@ -1,8 +1,12 @@
 ---
 id: api-overview
-title: Overview of the APIs
-sidebar_label: Overview APIs and Clients
+title: API Overview
+sidebar_label: APIs and Clients Overview
 description: "This section contains information about the different APIs and Clients to use with Miranum."
 ---
 
-Coming Soon! 
+This section contains all information about the different APIs and Clients which can be used with the **Miranum Connect**
+Framework. 
+
+In the subsections you will be able to find: 
+* [Cloud Events Specifications](./cloud-events/cloud-events-overview.md)

docs/apis/cloud-events/cloud-events-overview.md

@@ -0,0 +1,23 @@
+---
+id: cloud-events-overview
+title: Cloud Events Overview 
+sidebar_label: Overview 
+description: "This section provides an overview of the different Cloud Event commands which are supported by Miranum Connect."
+---
+# Overview
+
+:::::info
+CloudEvents is a [specification](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md) for describing event 
+data in a common way. CloudEvents seeks to dramatically simplify event declaration and delivery across services, platforms, and beyond!
+
+CloudEvents is a new effort, and it's still under active development. 
+However, its working group has received a surprising amount of industry interest, ranging from major cloud providers to 
+popular SaaS companies. The specification is now under the [Cloud Native Computing Foundation](https://cncf.io/).
+:::::
+
+**Miranum Connect** uses this standard to enable other software components to use its functionality / APIs. 
+The schema of currently available cloud events is documented in the [Commands](./commands/ActivateJobsRequests) subsection. 
+
+:::note 
+The gateway which will be able to consume the Cloud Events is still under development. 
+:::

docs/apis/cloud-events/commands/ActivateJobsRequests.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/ActivateJobsRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# ActivateJobsRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/ActivateJobsResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/ActivateJobsResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# ActivateJobsResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CancelProcessInstanceRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CancelProcessInstanceRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CancelProcessInstanceRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CancelProcessInstanceResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CancelProcessInstanceResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CancelProcessInstanceResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CompleteJobRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CompleteJobRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CompleteJobRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CompleteJobResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CompleteJobResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CompleteJobResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CreateProcessInstanceRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CreateProcessInstanceRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CompleteProcessInstanceRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/CreateProcessInstanceResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/CreateProcessInstanceResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# CreateProcessInstanceResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/DeployResourceRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/DeployResourceRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# DeployResourceRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/DeployResourceResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/DeployResourceResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# DeployResourceResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/FailJobRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/FailJobRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# FailJobRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/FailJobResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/FailJobResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# FailJobResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/PublishMessageRequest.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/PublishMessageRequest.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# PublishMessageRequest
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/cloud-events/commands/PublishMessageResponse.mdx

@@ -0,0 +1,11 @@
+import CodeBlock from '@theme/CodeBlock';
+import Schema from "../../static/schemas/bpmn/command/PublishMessageResponse.schema.json";
+import JSONSchemaViewer from "docusaurus-json-schema-plugin/lib/theme/JSONSchemaViewer";
+
+# PublishMessageResponse
+
+<JSONSchemaViewer schema={ Schema } />
+
+# Source:
+
+<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

docs/apis/static/schemas/bpmn/command/ActivateJobsRequest.schema.json

@@ -0,0 +1,34 @@
+{
+  "$id": "io.miranum.bpmn.command.v1.ActivateJobsRequest",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "type": {
+      "description": "the job type, as defined in the BPMN process",
+      "type": "string"
+    },
+    "worker": {
+      "description": "the name of the worker activating the jobs, mostly used for logging purposes",
+      "type": "string"
+    },
+    "timeout": {
+      "description": "a job returned after this call will not be activated by another call until the\ntimeout (in ms) has been reached",
+      "type": "number"
+    },
+    "maxJobsToActivate": {
+      "description": "the maximum jobs to activate by this request",
+      "type": "number"
+    },
+    "fetchVariable": {
+      "description": "a list of variables to fetch as the job variables; if empty, all visible variables at\nthe time of activation for the scope of the job will be returned",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "requestTimeout": {
+      "description": "The request will be completed when at least one job is activated or after the requestTimeout (in ms).\nif the requestTimeout = 0, a default timeout is used.\nif the requestTimeout < 0, long polling is disabled and the request is completed immediately, even when no job is activated.",
+      "type": "number"
+    }
+  }
+}

docs/apis/static/schemas/bpmn/command/ActivateJobsResponse.schema.json

@@ -0,0 +1,73 @@
+{
+  "$id": "io.miranum.bpmn.command.v1.ActivateJobsResponse",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "jobs": {
+      "description": "list of activated jobs",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ActivatedJob"
+      }
+    }
+  },
+  "definitions": {
+    "ActivatedJob": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "description": "the key, a unique identifier for the job",
+          "type": "number"
+        },
+        "type": {
+          "description": "the type of the job (should match what was requested)",
+          "type": "string"
+        },
+        "processInstanceKey": {
+          "description": "the job's process instance key",
+          "type": "number"
+        },
+        "bpmnProcessId": {
+          "description": "the bpmn process ID of the job process definition",
+          "type": "string"
+        },
+        "processDefinitionVersion": {
+          "description": "the version of the job process definition",
+          "type": "number"
+        },
+        "processDefinitionKey": {
+          "description": "the key of the job process definition",
+          "type": "number"
+        },
+        "elementId": {
+          "description": "the associated task element ID",
+          "type": "string"
+        },
+        "elementInstanceKey": {
+          "description": "the unique key identifying the associated task, unique within the scope of the\nprocess instance",
+          "type": "number"
+        },
+        "customHeaders": {
+          "description": "a set of custom headers defined during modelling; returned as a serialized\nJSON document",
+          "type": "string"
+        },
+        "worker": {
+          "description": "the name of the worker which activated this job",
+          "type": "string"
+        },
+        "retries": {
+          "description": "the amount of retries left to this job (should always be positive)",
+          "type": "number"
+        },
+        "deadline": {
+          "description": "when the job can be activated again, sent as a UNIX epoch timestamp",
+          "type": "number"
+        },
+        "variables": {
+          "description": "JSON document, computed at activation time, consisting of all visible variables to\nthe task scope",
+          "type": "string"
+        }
+      }
+    }
+  }
+}

docs/apis/static/schemas/bpmn/command/CancelProcessInstanceRequest.schema.json

@@ -0,0 +1,11 @@
+{
+  "$id": "io.miranum.bpmn.command.v1.CancelProcessInstanceRequest",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "processInstanceKey": {
+      "description": "the process instance key (as, for example, obtained from\nCreateProcessInstanceResponse)",
+      "type": "number"
+    }
+  }
+}

docs/apis/static/schemas/bpmn/command/CancelProcessInstanceResponse.schema.json

@@ -0,0 +1,5 @@
+{
+  "$id": "io.miranum.bpmn.command.v1.CancelProcessInstanceResponse",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object"
+}