feat: Zeebe REST API Explorer (integrated approach) (#3529)

* feat: configure zeebe api explorer

* feat: generate zeebe rest api docs

* feat: show correct version for Zeebe API Explorer

* chore: pass-through script to prettier so i can call it like
> [email protected] prettier
> prettier

Usage: prettier [options] [file/dir/glob ...]

By default, output is written to stdout.
Stdin is read if it is piped to Prettier and no files are given.

Output options:

  -c, --check              Check if the given files are formatted, print a human-friendly summary
                           message and paths to unformatted files (see also --list-different).
  -l, --list-different     Print the names of files that are different from Prettier's formatting (see also --check).
  -w, --write              Edit files in-place. (Beware!)

Format options:

  --arrow-parens <always|avoid>
                           Include parentheses around a sole arrow function parameter.
                           Defaults to always.
  --bracket-same-line      Put > of opening tags on the last line instead of on a new line.
                           Defaults to false.
  --no-bracket-spacing     Do not print spaces between brackets.
  --embedded-language-formatting <auto|off>
                           Control how Prettier formats quoted code embedded in the file.
                           Defaults to auto.
  --end-of-line <lf|crlf|cr|auto>
                           Which end of line characters to apply.
                           Defaults to lf.
  --html-whitespace-sensitivity <css|strict|ignore>
                           How to handle whitespaces in HTML.
                           Defaults to css.
  --jsx-single-quote       Use single quotes in JSX.
                           Defaults to false.
  --parser <flow|babel|babel-flow|babel-ts|typescript|acorn|espree|meriyah|css|less|scss|json|json5|json-stringify|graphql|markdown|mdx|vue|yaml|glimmer|html|angular|lwc>
                           Which parser to use.
  --print-width <int>      The line length where Prettier will try wrap.
                           Defaults to 80.
  --prose-wrap <always|never|preserve>
                           How to wrap prose.
                           Defaults to preserve.
  --quote-props <as-needed|consistent|preserve>
                           Change when properties in objects are quoted.
                           Defaults to as-needed.
  --no-semi                Do not print semicolons, except at the beginning of lines which may need them.
  --single-attribute-per-line
                           Enforce single attribute per line in HTML, Vue and JSX.
                           Defaults to false.
  --single-quote           Use single quotes instead of double quotes.
                           Defaults to false.
  --tab-width <int>        Number of spaces per indentation level.
                           Defaults to 2.
  --trailing-comma <all|es5|none>
                           Print trailing commas wherever possible when multi-line.
                           Defaults to all.
  --use-tabs               Indent with tabs instead of spaces.
                           Defaults to false.
  --vue-indent-script-and-style
                           Indent script and style tags in Vue files.
                           Defaults to false.

Config options:

  --config <path>          Path to a Prettier configuration file (.prettierrc, package.json, prettier.config.js).
  --no-config              Do not look for a configuration file.
  --config-precedence <cli-override|file-override|prefer-file>
                           Define in which order config files and CLI options should be evaluated.
                           Defaults to cli-override.
  --no-editorconfig        Don't take .editorconfig into account when parsing configuration.
  --find-config-path <path>
                           Find and print the path to a configuration file for the given input file.
  --ignore-path <path>     Path to a file with patterns describing files to ignore.
                           Multiple values are accepted.
                           Defaults to [.gitignore, .prettierignore].
  --plugin <path>          Add a plugin. Multiple plugins can be passed as separate `--plugin`s.
                           Defaults to [].
  --with-node-modules      Process files inside 'node_modules' directory.

Editor options:

  --cursor-offset <int>    Print (to stderr) where a cursor at the given position would move to after formatting.
                           This option cannot be used with --range-start and --range-end.
                           Defaults to -1.
  --range-end <int>        Format code ending at a given character offset (exclusive).
                           The range will extend forwards to the end of the selected statement.
                           This option cannot be used with --cursor-offset.
                           Defaults to Infinity.
  --range-start <int>      Format code starting at a given character offset.
                           The range will extend backwards to the start of the first line containing the selected statement.
                           This option cannot be used with --cursor-offset.
                           Defaults to 0.

Other options:

  --cache                  Only format changed files. Cannot use with --stdin-filepath.
                           Defaults to false.
  --cache-location <path>  Path to the cache file.
  --cache-strategy <metadata|content>
                           Strategy for the cache to use for detecting changed files.
  --no-color               Do not colorize error messages.
  --no-error-on-unmatched-pattern
                           Prevent errors when pattern is unmatched.
  --file-info <path>       Extract the following info (as JSON) for a given file path. Reported fields:
                           * ignored (boolean) - true if file path is filtered by --ignore-path
                           * inferredParser (string | null) - name of parser inferred from file path
  -h, --help <flag>        Show CLI usage, or details about the given flag.
                           Example: --help write
  -u, --ignore-unknown     Ignore unknown files.
  --insert-pragma          Insert @Format pragma into file's first docblock comment.
                           Defaults to false.
  --log-level <silent|error|warn|log|debug>
                           What level of logs to report.
                           Defaults to log.
  --require-pragma         Require either '@prettier' or '@Format' to be present in the file's first docblock comment
                           in order for it to be formatted.
                           Defaults to false.
  --stdin-filepath <path>  Path to the file to pretend that stdin comes from.
  --support-info           Print support information as JSON.
  -v, --version            Print Prettier version.

* refactor: align endpoint descriptions with other explorers

* oops: revert this https change that I keep making for some reason

* fix: override display of additionalProperties in schemas

* confused: I don't know why the generated docs need to be double-prettier'ed, but they do

* chore: update OpenAPI spec

* fix: adjust Zeebe API version based on spec

* feat: display an 'unreleased' banner at the top of the Zeebe Explorer

* feat: migrate zeebe rest api docs into main docs instance

* Revert "feat: show correct version for Zeebe API Explorer"

This reverts commit 6ebe63b.

* Revert "feat: display an 'unreleased' banner at the top of the Zeebe Explorer"

This reverts commit 4d7eec8.

* refactor: zeebe rest overview

* docs: describe auth for zeebe rest api

api/zeebe/post-generate.sh

@@ -0,0 +1,3 @@
+# The generator adds a version badge to the Introduction file, but 
+#   we already have a version badge from the main docs layout.
+sed -i '' '/Version: 0.1/d' docs/apis-tools/zeebe-api-rest/specifications/zeebe-rest-api.info.mdx

api/zeebe/zeebe-openapi.yaml

@@ -0,0 +1,388 @@
+openapi: "3.1.0"
+info:
+  title: Zeebe REST API
+  version: "0.1"
+  description: API for communicating with the Zeebe cluster.
+  license:
+    name: Zeebe Community License Version 1.1
+    url: https://github.com/camunda/zeebe/blob/main/licenses/ZEEBE-COMMUNITY-LICENSE-1.1.txt
+externalDocs:
+  description: Find out more
+  url: https://docs.camunda.io/docs/apis-tools/zeebe-api-rest/overview/
+
+servers:
+  - url: "{schema}://{host}:{port}/v1"
+    variables:
+      host:
+        default: localhost
+        description: The hostname of a Zeebe Gateway.
+      port:
+        default: "8080"
+        description: The port of the Zeebe REST API server.
+      schema:
+        default: http
+        description: The schema of the Zeebe REST API server.
+
+paths:
+  /topology:
+    get:
+      tags:
+        - Cluster
+      summary: Get cluster topology
+      description: Obtains the current topology of the cluster the gateway is part of.
+      responses:
+        "200":
+          $ref: "#/components/responses/TopologyResponse"
+  /user-tasks/{userTaskKey}/completion:
+    post:
+      tags:
+        - User task
+      summary: Complete a user task
+      description: Completes a user task with the given key.
+      parameters:
+        - name: userTaskKey
+          in: path
+          required: true
+          description: The key of the user task to complete.
+          schema:
+            type: integer
+            format: int64
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UserTaskCompletionRequest"
+
+      responses:
+        "204":
+          description: The user task was completed successfully.
+        "404":
+          description: The user task with the given key was not found.
+        "409":
+          description: >
+            The user task with the given key is in the wrong state currently.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+        "400":
+          description: >
+            The user task with the given key cannot be completed.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+  /user-tasks/{userTaskKey}/assignment:
+    post:
+      tags:
+        - User task
+      summary: Assign a user task
+      description: Assigns a user task with the given key to the given assignee.
+      parameters:
+        - name: userTaskKey
+          in: path
+          required: true
+          description: The key of the user task to assign.
+          schema:
+            type: integer
+            format: int64
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UserTaskAssignmentRequest"
+      responses:
+        "204":
+          description: The user task's assignment was adjusted.
+        "404":
+          description: The user task with the given key was not found.
+        "409":
+          description: >
+            The user task with the given key is in the wrong state currently.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+        "400":
+          description: >
+            The assignment of the user task with the given key cannot be completed.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+  /user-tasks/{userTaskKey}:
+    patch:
+      tags:
+        - User task
+      summary: Update a user task
+      description: Update a user task with the given key.
+      parameters:
+        - name: userTaskKey
+          in: path
+          required: true
+          description: The key of the user task to update.
+          schema:
+            type: integer
+            format: int64
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UserTaskUpdateRequest"
+      responses:
+        "204":
+          description: The user task was updated successfully.
+        "404":
+          description: The user task with the given key was not found.
+        "409":
+          description: >
+            The user task with the given key is in the wrong state currently.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+        "400":
+          description: >
+            The user task with the given key cannot be updated.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+  /user-tasks/{userTaskKey}/assignee:
+    delete:
+      tags:
+        - User task
+      summary: Unassign a user task
+      description: Removes the assignee of a task with the given key.
+      parameters:
+        - name: userTaskKey
+          in: path
+          required: true
+          description: The key of the user task.
+          schema:
+            type: integer
+            format: int64
+      responses:
+        "204":
+          description: The user task was unassigned successfully.
+        "404":
+          description: The user task with the given key was not found.
+        "409":
+          description: >
+            The user task with the given key is in the wrong state currently.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+        "400":
+          description: >
+            The user task with the given key cannot be unassigned.
+            More details are provided in the response body.
+          $ref: "#/components/responses/ProblemResponse"
+
+components:
+  responses:
+    TopologyResponse:
+      description: Obtains the current topology of the cluster the gateway is part of.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/TopologyResponse"
+    ProblemResponse:
+      description: Response for exceptional uses cases, providing more details.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/ProblemDetail"
+
+  schemas:
+    TopologyResponse:
+      description: The response of a topology request.
+      type: object
+      properties:
+        brokers:
+          description: A list of brokers that are part of this cluster.
+          type: array
+          nullable: true
+          items:
+            $ref: "#/components/schemas/BrokerInfo"
+        clusterSize:
+          description: The number of brokers in the cluster.
+          type: integer
+          format: int32
+          nullable: true
+        partitionsCount:
+          description: The number of partitions are spread across the cluster.
+          type: integer
+          format: int32
+          nullable: true
+        replicationFactor:
+          description: The configured replication factor for this cluster.
+          type: integer
+          format: int32
+          nullable: true
+        gatewayVersion:
+          description: The version of the Zeebe Gateway.
+          type: string
+          nullable: true
+    BrokerInfo:
+      description: Provides information on a broker node.
+      type: object
+      properties:
+        nodeId:
+          description: The unique (within a cluster) node ID for the broker.
+          type: integer
+          format: int32
+        host:
+          description: The hostname for reaching the broker.
+          type: string
+        port:
+          description: The port for reaching the broker.
+          type: integer
+          format: int32
+        partitions:
+          description: A list of partitions managed or replicated on this broker.
+          type: array
+          items:
+            $ref: "#/components/schemas/Partition"
+        version:
+          description: The broker version.
+          type: string
+    Partition:
+      description: Provides information on a partition within a broker node.
+      type: object
+      properties:
+        partitionId:
+          description: The unique ID of this partition.
+          type: integer
+          format: int32
+        role:
+          description: Describes the Raft role of the broker for a given partition.
+          type: string
+          enum:
+            - leader
+            - follower
+            - inactive
+        health:
+          description: Describes the current health of the partition.
+          type: string
+          enum:
+            - healthy
+            - unhealthy
+            - dead
+    UserTaskCompletionRequest:
+      type: object
+      properties:
+        variables:
+          description: The variables to complete the user task with.
+          type: object
+          nullable: true
+          $ref: "#/components/schemas/Variables"
+        action:
+          description: >
+            A custom action value that will be accessible from user task events resulting
+            from this endpoint invocation. If not provided, it will default to "complete".
+          type: string
+          nullable: true
+    UserTaskAssignmentRequest:
+      type: object
+      properties:
+        assignee:
+          description: The assignee for the user task. The assignee must not be empty or `null`.
+          type: string
+          nullable: false
+        allowOverride:
+          description: >
+            By default, the task is reassigned if it was already assigned. Set this to `false`
+            to return an error in such cases. The task must then first be unassigned to
+            be assigned again. Use this when you have users picking from group task
+            queues to prevent race conditions.
+          type: boolean
+          nullable: true
+        action:
+          description: >
+            A custom action value that will be accessible from user task events resulting
+            from this endpoint invocation. If not provided, it will default to "assign".
+          type: string
+          nullable: true
+    UserTaskUpdateRequest:
+      type: object
+      properties:
+        changeset:
+          description: |
+            JSON object with changed task attribute values.
+
+            The following attributes can be adjusted with this endpoint, additional attributes
+            will be ignored:
+
+            * `candidateGroups` - reset by providing an empty list
+            * `candidateUsers` - reset by providing an empty list
+            * `dueDate` - reset by providing an empty String
+            * `followUpDate` - reset by providing an empty String
+
+            Providing any of those attributes with a `null` value or omitting it preserves
+            the persisted attribute's value.
+
+            The assignee cannot be adjusted with this endpoint, use the Assign task endpoint.
+            This ensures correct event emission for assignee changes.
+          type: object
+          nullable: true
+          $ref: "#/components/schemas/Changeset"
+        action:
+          description: >
+            A custom action value that will be accessible from user task events resulting
+            from this endpoint invocation. If not provided, it will default to "update".
+          type: string
+          nullable: true
+    Variables:
+      description: A map of variables.
+      type: object
+      additionalProperties: true
+    Changeset:
+      description: A map of changes.
+      type: object
+      additionalProperties: true
+      properties:
+        dueDate:
+          type: string
+          format: date-time
+          description: The due date of the task. Reset by providing an empty String.
+          nullable: true
+        followUpDate:
+          type: string
+          format: date-time
+          description: The follow-up date of the task. Reset by providing an empty String.
+          nullable: true
+        candidateUsers:
+          type: array
+          description: The list of candidate users of the task. Reset by providing an empty list.
+          items:
+            type: string
+          nullable: true
+        candidateGroups:
+          type: array
+          description: The list of candidate groups of the task. Reset by providing an empty list.
+          items:
+            type: string
+          nullable: true
+    ProblemDetail:
+      description: >
+        A Problem detail object as described in [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).
+        There may be additional properties specific to the problem type.
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri
+          description: A URI identifying the problem type.
+          default: about:blank
+        title:
+          type: string
+          description: A summary of the problem type.
+        status:
+          type: integer
+          format: int32
+          description: The HTTP status code for this problem.
+          minimum: 400
+          maximum: 600
+        detail:
+          type: string
+          description: An explanation of the problem in more detail.
+        instance:
+          type: string
+          format: uri
+          description: A URI identifying the origin of the problem.
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT