User Operations OpenApi

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

@@ -0,0 +1,66 @@
+<@lib.parameter
+    name = "id"
+    location = "query"
+    type = "string"
+    desc = "Filter by user id"/>
+
+<@lib.property
+    name = "tenantIdIn"
+    type = "array"
+    itemType = "string"
+    desc = "Filter by a list of user ids. Must be a JSON array of Strings." />
+
+<@lib.parameter
+    name = "firstName"
+    location = "query"
+    type = "string"
+    desc = "Filter by the first name of the user. Exact match."/>
+
+<@lib.parameter
+    name = "firstNameLike"
+    location = "query"
+    type = "string"
+    desc = "Filter by the first name that the parameter is a substring of."/>
+
+<@lib.parameter
+    name = "lastName"
+    location = "query"
+    type = "string"
+    desc = "Filter by the last name of the user. Exact match."/>
+
+<@lib.parameter
+    name = "lastNameLike"
+    location = "query"
+    type = "string"
+    desc = "Filter by the last name that the parameter is a substring of."/>
+
+<@lib.parameter
+    name = "email"
+    location = "query"
+    type = "string"
+    desc = "Filter by the email of the user. Exact match."/>
+
+<@lib.parameter
+    name = "emailLike"
+    location = "query"
+    type = "string"
+    desc = "Filter by the email that the parameter is a substring of."/>
+
+<@lib.parameter
+    name = "memberOfGroup"
+    location = "query"
+    type = "string"
+    desc = "Filter for users which are members of the given group."/>
+
+<@lib.parameter
+    name = "memberOfTenant"
+    location = "query"
+    type = "string"
+    desc = "Filter for users which are members of the given tenant."/>
+
+<@lib.parameter
+    name = "potentialStarter"
+    location = "query"
+    type = "string"
+    last = last
+    desc = "Only select Users that are potential starter for the given process definition."/>

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

@@ -3,7 +3,7 @@
     <@lib.property
         name = "rel"
         type = "string"
-        desc = "The relation of the link to the object that belogs to." />
+        desc = "The relation of the link to the object that belongs to." />
 
     <@lib.property
         name = "href"

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

@@ -0,0 +1,3 @@
+<@lib.dto
+    extends = "LinkableDto" >
+</@lib.dto>

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

@@ -0,0 +1,15 @@
+<@lib.dto>
+
+    <@lib.property
+        name = "password"
+        type = "string"
+        desc = "The users new password." />
+
+    <@lib.property
+        name = "authenticatedUserPassword"
+        type = "string"
+        last = true
+        desc = "The password of the authenticated user who changes the password of the user
+                          (i.e., the user with passed id as path parameter)." />
+
+</@lib.dto>

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

@@ -0,0 +1,19 @@
+<@lib.dto>
+
+    <@lib.property
+        name = "profile"
+        type = "ref"
+        dto = "UserProfileDto"
+        desc = "A JSON object containing variable key-value pairs.
+        The object contains the following properties:
+        id (String), firstName (String), lastName (String) and email (String). "/>
+
+    <@lib.property
+        name = "credentials"
+        type = "ref"
+        dto = "UserCredentialsDto"
+        last = true
+        desc = "A JSON object containing variable key-value pairs.
+        The object contains the following property: password (String).  "/>
+
+</@lib.dto>

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

@@ -0,0 +1,24 @@
+<@lib.dto>
+
+    <@lib.property
+        name = "id"
+        type = "string"
+        desc = "The id of the user." />
+
+    <@lib.property
+        name = "firstName"
+        type = "string"
+        desc = "The first name of the user." />
+
+    <@lib.property
+        name = "lastName"
+        type = "string"
+        desc = "The first name of the user." />
+
+    <@lib.property
+         name = "email"
+         type = "string"
+         last = true
+         desc = "The email of the user." />
+
+</@lib.dto>

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

@@ -0,0 +1,37 @@
+{
+
+  <@lib.endpointInfo
+      id = "getUserCount"
+      tag = "User"
+      desc = "Queries for the number of deployments that fulfill given parameters. Takes the same parameters as the
+      [Get Users](${docsUrl}/reference/rest/user/get-query/) method." />
+
+  "parameters" : [
+
+    <#assign last = true >
+    <#include "/lib/commons/user-query-params.ftl" >
+
+  ],
+
+  "responses" : {
+
+    <@lib.response
+        code = "200"
+        dto = "CountResultDto"
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/user/count?firstName=John`",
+                       "value": {
+                         "count": 2
+                       }
+                     }'] />
+
+    <@lib.response
+        code = "400"
+        dto = "ExceptionDto"
+        last = true
+        desc = "Returned if some of the query parameters are invalid, for example, if an invalid operator for variable
+                comparison is used. See the [Introduction](${docsUrl}/reference/rest/overview/#error-handling)
+                for the error response format." />
+    }
+}

engine-rest/engine-rest-openapi/src/main/templates/paths/user/create/post.ftl

@@ -0,0 +1,33 @@
+{
+
+  <@lib.endpointInfo
+      id = "createUser"
+      tag = "User"
+      desc = "Create a new user." />
+
+  <@lib.requestBody
+      mediaType = "application/json"
+      dto = "UserDto"
+      examples = ['"example-1": {
+                     "summary": "POST /user/create",
+                     "value": {
+                         "profile": {
+                             "id": "jonny1",
+                             "firstName": "John",
+                             "lastName": "Doe",
+                             "email": "anEmailAddress"
+                             },
+                         "credentials": {
+                            "password": "s3cret"
+                        }
+                   }
+                   }'] />
+
+  "responses" : {
+
+    <@lib.response
+        code = "204"
+        last = true
+        desc = "Request successful." />
+  }
+}

engine-rest/engine-rest-openapi/src/main/templates/paths/user/get.ftl

@@ -0,0 +1,57 @@
+{
+
+  <@lib.endpointInfo
+      id = "getUsers"
+      tag = "User"
+      desc = "Query for a list of users using a list of parameters.
+               The size of the result set can be retrieved by using the Get User Count method.
+               [Get User Count](${docsUrl}/reference/rest/user/get-query-count/) method." />
+
+  "parameters" : [
+
+    <#assign last = false >
+    <#include "/lib/commons/user-query-params.ftl" >
+
+    <#assign sortBy = [ '"userId"', '"firstName"', '"lastName"', '"email"' ] >
+    <#include "/lib/commons/sort-params.ftl" >
+
+    <#assign last = true >
+    <#include "/lib/commons/pagination-params.ftl" >
+
+  ],
+
+  "responses" : {
+
+    <@lib.response
+        code = "200"
+        dto = "UserProfileDto"
+        array = true
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/user?firstName=John`",
+                       "value": [
+                         {
+                           "id": "jonny1",
+                           "firstName": "John",
+                           "lastName": "Doe",
+                           "email": "anEmailAddress"
+                         },
+                         {
+                            "id": "jonny2",
+                            "firstName": "John",
+                            "lastName": "Smoe",
+                            "email": "anotherEmailAddress"
+                          }
+                       ]
+                     }'] />
+
+    <@lib.response
+        code = "400"
+        dto = "ExceptionDto"
+        last = true
+        desc = "Returned if some of the query parameters are invalid, for example if a `sortOrder` parameter is supplied,
+                but no `sortBy`, or if an invalid operator for variable comparison is used. See the
+                [Introduction](${docsUrl}/reference/rest/overview/#error-handling)
+                for the error response format." />
+  }
+}

engine-rest/engine-rest-openapi/src/main/templates/paths/user/options.ftl

@@ -0,0 +1,32 @@
+{
+
+  <@lib.endpointInfo
+      id = "availableOperations"
+      tag = "User"
+      desc = "The /user resource supports two custom OPTIONS requests, one for the resource as such
+      and one for individual user instances. The OPTIONS request allows checking for the set of
+      available operations that the currently authenticated user can perform on the /user resource.
+      If the user can perform an operation or not may depend on various things, including the user's
+      authorizations to interact with this resource and the internal configuration of the process
+      engine." />
+
+  "responses" : {
+
+    <@lib.response
+        mediaType = "application/json"
+        code = "200"
+        dto = "ResourceOptionsDto"
+        last = true
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/user/aUserId`",
+                       "value": {
+                         "links":[
+                          {"method":"GET","href":"http://localhost:8080/camunda/api/engine/engine/default/user/peter/profile","rel":"self"},
+                          {"method":"DELETE","href":"http://localhost:8080/camunda/api/engine/engine/default/user/peter","rel":"delete"},
+                          {"method":"PUT","href":"http://localhost:8080/camunda/api/engine/engine/default/user/peter/profile","rel":"update"}
+                          ]
+                          }
+                     }'] />
+    }
+}

engine-rest/engine-rest-openapi/src/main/templates/paths/user/{id}/credentials/put.ftl

@@ -0,0 +1,75 @@
+{
+
+  <@lib.endpointInfo
+      id = "updateCredentials"
+      tag = "User"
+      desc = "Updates a user’s credentials (password)" />
+
+  "parameters" : [
+
+     <@lib.parameter
+         name = "id"
+         location = "path"
+         type = "string"
+         required = true
+         desc = "The id of the user to be updated." />
+
+      <@lib.parameter
+          name = "password"
+          location = "query"
+          type = "string"
+          required = true
+          desc = "The users new password." />
+
+      <@lib.parameter
+          name = "authenticatedUserPassword"
+          location = "query"
+          type = "string"
+          required = true
+          last = true
+          desc = "The password of the authenticated user who changes the password of the user
+          (i.e., the user with passed id as path parameter)." />
+  ],
+
+  <@lib.requestBody
+        mediaType = "application/json"
+        dto = "UserCredentialsDto"
+        examples = ['"example-1": {
+                             "summary": "PUT /user/jonny1/credentials",
+                             "value": {
+                               "password": "s3cr3t",
+                               "authenticatedUserPassword" : "demo"
+                             }
+                           }'] />
+
+  "responses" : {
+
+    <@lib.response
+        code = "200"
+        desc = "Request successful." />
+
+    <@lib.response
+        code = "403"
+        mediaType = "application/json"
+        desc = "Identity service is read-only (Cannot modify users / groups / memberships)." />
+
+    <@lib.response
+        code = "400"
+        mediaType = "application/json"
+        desc = "The authenticated user password does not match" />
+
+    <@lib.response
+        code = "404"
+        mediaType = "application/json"
+        desc = "If the corresponding user cannot be found" />
+
+    <@lib.response
+       code = "500"
+       mediaType = "application/json"
+       dto = "ExceptionDto"
+       last = true
+       desc = "The user could not be updated due to an internal server error. See the
+               [Introduction](${docsUrl}/reference/rest/overview/#error-handling)
+               for the error response format." />
+  }
+}