feat(openapi): add job definition endpoints

* adds all endpoints to OpenAPI description
* splits JobDefinitionSuspensionStateDto into two DTOs for better schema clarity,
  since the parameters for updating multiple instances are not relevant for the
  update of a single instance

related to CAM-11544

engine-rest/engine-rest-openapi/src/main/templates/lib/commons/job-definition-query-params.ftl

@@ -0,0 +1,79 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/get-query/index.html -->
+
+<#assign sortByValues = [
+  '"jobDefinitionId"',
+  '"activityId"',
+  '"processDefinitionId"',
+  '"processDefinitionKey"',
+  '"jobType"',
+  '"jobConfiguration"',
+  '"tenantId"'
+]>
+
+<#if requestMethod == "GET">
+  <#assign listSeparator = " and comma-separated">
+<#elseif requestMethod == "POST">
+  <#assign listSeparator = "">
+</#if>
+
+<#assign params = {
+  "jobDefinitionId": {
+    "type": "string",
+    "desc": "Filter by job definition id."
+  },
+  "activityIdIn": {
+    "type": "array",
+    "itemType": "string",
+    "desc": "Only include job definitions which belong to one of the passed${listSeparator} activity ids."
+  },
+  "processDefinitionId": {
+    "type": "string",
+    "desc": "Only include job definitions which exist for the given process definition id."
+  },
+  "processDefinitionKey": {
+    "type": "string",
+    "desc": "Only include job definitions which exist for the given process definition key."
+  },
+  "jobType": {
+    "type": "string",
+    "desc": "Only include job definitions which exist for the given job type. See the
+             [User Guide](${docsUrl}/user-guide/process-engine/the-job-executor/#job-creation)
+             for more information about job types."
+  },
+  "jobConfiguration": {
+    "type": "string",
+    "desc": "Only include job definitions which exist for the given job configuration. For example: for
+             timer jobs it is the timer configuration."
+  },
+  "active": {
+    "type": "boolean",
+    "desc": "Only include active job definitions. Value may only be `true`, as `false` is the default
+             behavior."
+  },
+  "suspended": {
+    "type": "boolean",
+    "desc": "Only include suspended job definitions. Value may only be `true`, as `false` is the
+             default behavior."
+  },
+  "withOverridingJobPriority": {
+    "type": "boolean",
+    "desc": "Only include job definitions that have an overriding job priority defined. The only
+             effective value is `true`. If set to `false`, this filter is not applied."
+  },
+  "tenantIdIn": {
+    "type": "array",
+    "itemType": "string",
+    "desc": "Only include job definitions which belong to one of the passed${listSeparator} tenant
+             ids."
+  },
+  "withoutTenantId": {
+    "type": "boolean",
+    "desc": "Only include job definitions which belong to no tenant. Value may only be `true`, as
+             `false` is the default behavior."
+  },
+  "includeJobDefinitionsWithoutTenantId": {
+    "type": "boolean",
+    "desc": "Include job definitions which belong to no tenant. Can be used in combination with
+             `tenantIdIn`. Value may only be `true`, as `false` is the default behavior."
+  }
+}>

engine-rest/engine-rest-openapi/src/main/templates/main.ftl

@@ -58,6 +58,7 @@
     {"name": "Identity"},
     {"name": "Incident"},
     {"name": "Job"},
+    {"name": "Job Definition"},
     {"name": "Message"},
     {"name": "Metrics"},
     {"name": "Migration"},

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/SuspensionStateDto.ftl

@@ -1,14 +1,15 @@
 <#macro dto_macro docsUrl="">
 <@lib.dto>
 
-    <#-- NOTE: Please adding any changes, if necessary, to:
+    <#-- NOTE: When adding any changes, if necessary, to:
          * ProcessDefinitionSuspensionStateDto or JobSuspensionStateDto or create a new file
          * ... -->
     <@lib.property
         name = "suspended"
         type = "boolean"
-        desc = "A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, or batch).
-                When the value is set to true, the given instance will be suspended and when the value is set to false,
+        desc = "A Boolean value which indicates whether to activate or suspend a given instance 
+                (e.g. process instance, job, job definition, or batch). When the value is set to true, 
+                the given instance will be suspended and when the value is set to false, 
                 the given instance will be activated."
         last = true />
 

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/JobDefinitionDto.ftl

@@ -0,0 +1,75 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/get-query/index.html -->
+<#macro dto_macro docsUrl="">
+<@lib.dto >
+
+    <@lib.property
+        name = "id"
+        type = "string"
+        desc = "The id of the job definition."
+    />
+
+    <@lib.property
+        name = "processDefinitionId"
+        type = "string"
+        desc = "The id of the process definition this job definition is associated with."
+    />
+
+    <@lib.property
+        name = "processDefinitionKey"
+        type = "string"
+        desc = "The key of the process definition this job definition is associated with."
+    />
+
+    <@lib.property
+        name = "activityId"
+        type = "string"
+        desc = "The id of the activity this job definition is associated with."
+    />
+
+    <@lib.property
+        name = "jobType"
+        type = "string"
+        desc = "The type of the job which is running for this job definition. See the
+                [User Guide](${docsUrl}/user-guide/process-engine/the-job-executor/#job-creation)
+                for more information about job types."
+    />
+
+    <@lib.property
+        name = "jobConfiguration"
+        type = "string"
+        desc = "The configuration of a job definition provides details about the jobs which will be
+                created. For example: for timer jobs it is the timer configuration."
+    />
+
+    <@lib.property
+        name = "overridingJobPriority"
+        type = "integer"
+        format = "int64"
+        desc = "The execution priority defined for jobs that are created based on this definition.
+                May be `null` when the priority has not been overridden on the job
+                definition level."
+    />
+
+    <@lib.property
+        name = "suspended"
+        type = "boolean"
+        desc = "Indicates whether this job definition is suspended or not."
+    />
+
+    <@lib.property
+        name = "tenantId"
+        type = "string"
+        desc = "The id of the tenant this job definition is associated with."
+    />
+
+    <@lib.property
+        name = "deploymentId"
+        type = "string"
+        desc = "The id of the deployment this job definition is related to. In a deployment-aware
+                setup, this leads to all jobs of the same definition being executed
+                on the same node."
+        last = true
+    />
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/JobDefinitionPriorityDto.ftl

@@ -0,0 +1,27 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/put-set-job-priority/index.html -->
+<#macro dto_macro docsUrl="">
+<@lib.dto>
+
+    <@lib.property
+        name = "priority"
+        type = "integer"
+        format = "int64"
+        desc = "The new execution priority number for jobs of the given definition. The
+                definition's priority can be reset by using the value `null`. In
+                that case, the job definition's priority no longer applies but a new
+                job's priority is determined as specified in the process model."
+    />
+
+
+    <@lib.property
+        name = "includeJobs"
+        type = "boolean"
+        desc = "A boolean value indicating whether existing jobs of the given definition should
+                receive the priority as well. Default value is `false`. Can only be
+                `true` when the __priority__ parameter is not `null`."
+        last = true
+    />
+
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/JobDefinitionQueryDto.ftl

@@ -0,0 +1,20 @@
+<#macro dto_macro docsUrl="">
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job/post-query/index.html -->
+<@lib.dto desc = "A Job definition query which defines a list of Job definitions">
+
+    <#assign requestMethod="POST">
+    <#include "/lib/commons/job-definition-query-params.ftl">
+    <@lib.properties params/>    
+    "sorting": {
+       "type": "array",
+       "description": "An array of criteria to sort the result by. Each element of the array is
+                       an object that specifies one ordering. The position in the array
+                       identifies the rank of an ordering, i.e., whether it is primary, secondary,
+                       etc. Sorting has no effect for `count` endpoints.",
+       "items":
+         <#assign last = true>
+         <#include "/lib/commons/sort-props.ftl">
+    }
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/JobDefinitionSuspensionStateDto.ftl

@@ -0,0 +1,32 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/put-activate-suspend-by-id/index.html -->
+<#macro dto_macro docsUrl="">
+
+<#-- This DTO is also used in JobDefinitionsSuspensionStateDto that caters updating multiple definitions at once and 
+     provides additional parameters for that which don't make sense here. Please also consider this other DTO when
+     making changes here -->
+<@lib.dto extends="SuspensionStateDto">
+
+    <@lib.property
+        name = "includeJobs"
+        type = "boolean"
+        desc = "A `Boolean` value which indicates whether to activate or suspend also all jobs of
+                the referenced job definitions. When the value is set to `true`, all jobs
+                of the provided job definitions will be activated or suspended and
+                when the value is set to `false`, the suspension state of all jobs
+                of the provided job definitions will not be updated."
+    />
+
+
+    <@lib.property
+        name = "executionDate"
+        type = "string"
+        desc = "The date on which the referenced job definitions will be activated or suspended. If null,
+                the suspension state of the given job definitions is updated
+                immediately. By [default](${docsUrl}/reference/rest/overview/date-format/), the date must have the format `yyyy-MM-
+                dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`."
+        last = true
+    />
+
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/JobDefinitionsSuspensionStateDto.ftl

@@ -0,0 +1,50 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/put-activate-suspend-by-id/index.html -->
+<#macro dto_macro docsUrl="">
+
+<#assign noteProcessDefinitionKey = "Note that this parameter will only be considered 
+                                     in combination with `processDefinitionKey`." >
+
+<#-- This DTO provides additional parameters that only make sense in the context of updating multiple
+     definitions at once. Please also consider the parent DTO when making changes here -->
+<@lib.dto extends="JobDefinitionSuspensionStateDto"
+          desc = "Defines by which selection criterion to activate or suspend job definitions.
+                  The selection criteria are mutually exclusive and can only be one of:
+                  * `processDefinitionId`
+                  * `processDefinitionKey`">
+
+    <@lib.property
+        name = "processDefinitionId"
+        type = "string"
+        desc = "The process definition id of the job definitions to activate or suspend."
+    />
+
+    <@lib.property
+        name = "processDefinitionKey"
+        type = "string"
+        desc = "The process definition key of the job definitions to activate or suspend."
+    />
+
+
+    <@lib.property
+        name = "processDefinitionTenantId"
+        type = "string"
+        desc = "Only activate or suspend job definitions of a process definition which belongs to a
+                tenant with the given id.
+
+                ${noteProcessDefinitionKey}"
+    />
+
+
+    <@lib.property
+        name = "processDefinitionWithoutTenantId"
+        type = "string"
+        desc = "Only activate or suspend job definitions of a process definition which belongs to
+                no tenant. Value may only be `true`, as `false` is the default
+                behavior.
+
+                ${noteProcessDefinitionKey}"
+        last = true
+    />
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/paths/job-definition/count/get.ftl

@@ -0,0 +1,54 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/job-definition/get-query-count/index.html -->
+<#macro endpoint_macro docsUrl="">
+{
+  <@lib.endpointInfo
+      id = "getJobDefinitionsCount"
+      tag = "Job Definition"
+      summary = "Get Job Definition Count"
+      desc = "Queries for the number of job definitions that fulfill given parameters.
+              Takes the same parameters as the
+              [Get Job Definitions](${docsUrl}/reference/rest/job-definition/get-query/)
+              method."
+  />
+
+  "parameters" : [
+
+    <#assign last = true >
+    <#assign requestMethod="GET"/>
+    <#include "/lib/commons/job-definition-query-params.ftl" >
+    <@lib.parameters
+        object = params
+        last = last
+    />
+
+  ],
+
+  "responses": {
+
+    <@lib.response
+        code = "200"
+        dto = "CountResultDto"
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/job-definition/count?activityIdIn=ServiceTask1,ServiceTask2`",
+                       "description": "GET `/job-definition/count?activityIdIn=ServiceTask1,ServiceTask2`",
+                       "value": {
+                         "count": 2
+                       }
+                     }']
+    />
+
+    <@lib.response
+        code = "400"
+        dto = "ExceptionDto"
+        desc = "Returned if some of the query parameters are invalid, for example if a `sortOrder`
+                parameter is supplied, but no `sortBy`. See the
+                [Introduction](${docsUrl}/reference/rest/overview/#error-handling)
+                for the error response format."
+        last = true
+    />
+
+  }
+
+}
+</#macro>