Add description to token and getPersonalAccessTokens() (#1232)

Author: jmini

gitlab4j-api/src/main/java/org/gitlab4j/api/GroupApi.java

@@ -2375,16 +2375,42 @@ public GroupAccessToken getGroupAccessToken(Object groupIdOrPath, Long tokenId)
      * @param accessLevel Access level. Valid values are {@link AccessLevel#GUEST}, {@link AccessLevel#REPORTER}, {@link AccessLevel#DEVELOPER}, {@link AccessLevel#MAINTAINER}, and {@link AccessLevel#OWNER}.
      * @return the created GroupAccessToken instance
      * @throws GitLabApiException if any exception occurs
+     * @deprecated use {@link #createGroupAccessToken(Object, String, String, Date, Scope[], AccessLevel)}
      */
+    @Deprecated
     public GroupAccessToken createGroupAccessToken(
             Object groupIdOrPath, String name, Date expiresAt, Scope[] scopes, AccessLevel accessLevel)
             throws GitLabApiException {
+        return createGroupAccessToken(groupIdOrPath, name, null, expiresAt, scopes, accessLevel);
+    }
+    /**
+     * Create a group access token. You must have the Owner role for the group to create group access tokens.
+     *
+     * <pre><code>GitLab Endpoint: POST /groups/:id/access_tokens</code></pre>
+     *
+     * @param groupIdOrPath the group in the form of an Long(ID), String(path), or Group instance
+     * @param name the name of the group access token, required
+     * @param expiresAt the expiration date of the group access token, optional
+     * @param scopes an array of scopes of the group access token
+     * @param accessLevel Access level. Valid values are {@link AccessLevel#GUEST}, {@link AccessLevel#REPORTER}, {@link AccessLevel#DEVELOPER}, {@link AccessLevel#MAINTAINER}, and {@link AccessLevel#OWNER}.
+     * @return the created GroupAccessToken instance
+     * @throws GitLabApiException if any exception occurs
+     */
+    public GroupAccessToken createGroupAccessToken(
+            Object groupIdOrPath,
+            String name,
+            String description,
+            Date expiresAt,
+            Scope[] scopes,
+            AccessLevel accessLevel)
+            throws GitLabApiException {
         if (scopes == null || scopes.length == 0) {
             throw new RuntimeException("scopes cannot be null or empty");
         }
 
         GitLabApiForm formData = new GitLabApiForm()
                 .withParam("name", name, true)
+                .withParam("description", description)
                 .withParam("scopes", Arrays.asList(scopes))
                 .withParam("expires_at", ISO8601.dateOnly(expiresAt))
                 .withParam("access_level", accessLevel);

gitlab4j-api/src/main/java/org/gitlab4j/api/PersonalAccessTokenApi.java

@@ -1,7 +1,9 @@
 package org.gitlab4j.api;
 
 import java.util.Date;
+import java.util.List;
 
+import jakarta.ws.rs.core.GenericType;
 import jakarta.ws.rs.core.Response;
 
 import org.gitlab4j.api.models.PersonalAccessToken;
@@ -66,6 +68,20 @@ public PersonalAccessToken rotatePersonalAccessToken(String id, Date expiresAt)
         return (response.readEntity(PersonalAccessToken.class));
     }
 
+    /**
+     * Get information about the personal access token used in the request header.
+     * Only working with GitLab 16.0 and above.
+     *
+     * <pre><code>GitLab Endpoint: GET /personal_access_tokens</code></pre>
+     *
+     * @return the specified PersonalAccessToken.
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<PersonalAccessToken> getPersonalAccessTokens() throws GitLabApiException {
+        Response response = get(Response.Status.OK, null, "personal_access_tokens");
+        return response.readEntity(new GenericType<List<PersonalAccessToken>>() {});
+    }
+
     /**
      * Get information about the personal access token used in the request header.
      * Only working with GitLab 16.0 and above.

gitlab4j-api/src/main/java/org/gitlab4j/api/UserApi.java

@@ -994,7 +994,7 @@ public Optional<ImpersonationToken> getOptionalImpersonationToken(Object userIdO
      */
     public ImpersonationToken createImpersonationToken(
             Object userIdOrUsername, String name, Date expiresAt, Scope[] scopes) throws GitLabApiException {
-        return createPersonalAccessTokenOrImpersonationToken(userIdOrUsername, name, expiresAt, scopes, true);
+        return createPersonalAccessTokenOrImpersonationToken(userIdOrUsername, name, null, expiresAt, scopes, true);
     }
 
     /**
@@ -1028,10 +1028,32 @@ public void revokeImpersonationToken(Object userIdOrUsername, Long tokenId) thro
      * @param scopes an array of scopes of the personal access token
      * @return the created PersonalAccessToken instance
      * @throws GitLabApiException if any exception occurs
+     * @deprecated use {@link #createPersonalAccessToken(Object, String, String, Date, Scope[])}n
      */
+    @Deprecated
     public ImpersonationToken createPersonalAccessToken(
             Object userIdOrUsername, String name, Date expiresAt, Scope[] scopes) throws GitLabApiException {
-        return createPersonalAccessTokenOrImpersonationToken(userIdOrUsername, name, expiresAt, scopes, false);
+        return createPersonalAccessTokenOrImpersonationToken(userIdOrUsername, name, null, expiresAt, scopes, false);
+    }
+
+    /**
+     * Create a personal access token.  Available only for admin users.
+     *
+     * <pre><code>GitLab Endpoint: POST /users/:user_id/personal_access_tokens</code></pre>
+     *
+     * @param userIdOrUsername the user in the form of an Integer(ID), String(username), or User instance
+     * @param name the name of the personal access token, required
+     * @param description description of personal access token, optional
+     * @param expiresAt the expiration date of the personal access token, optional
+     * @param scopes an array of scopes of the personal access token
+     * @return the created PersonalAccessToken instance
+     * @throws GitLabApiException if any exception occurs
+     */
+    public ImpersonationToken createPersonalAccessToken(
+            Object userIdOrUsername, String name, String description, Date expiresAt, Scope[] scopes)
+            throws GitLabApiException {
+        return createPersonalAccessTokenOrImpersonationToken(
+                userIdOrUsername, name, description, expiresAt, scopes, false);
     }
 
     /**
@@ -1054,15 +1076,22 @@ public void revokePersonalAccessToken(Long tokenId) throws GitLabApiException {
     // as per https://docs.gitlab.com/ee/api/README.html#impersonation-tokens, impersonation tokens are a type of
     // personal access token
     private ImpersonationToken createPersonalAccessTokenOrImpersonationToken(
-            Object userIdOrUsername, String name, Date expiresAt, Scope[] scopes, boolean impersonation)
+            Object userIdOrUsername,
+            String name,
+            String description,
+            Date expiresAt,
+            Scope[] scopes,
+            boolean impersonation)
             throws GitLabApiException {
 
         if (scopes == null || scopes.length == 0) {
             throw new RuntimeException("scopes cannot be null or empty");
         }
 
-        GitLabApiForm formData =
-                new GitLabApiForm().withParam("name", name, true).withParam("expires_at", expiresAt);
+        GitLabApiForm formData = new GitLabApiForm()
+                .withParam("name", name, true)
+                .withParam("description", description)
+                .withParam("expires_at", expiresAt);
 
         for (Scope scope : scopes) {
             formData.withParam("scopes[]", scope.toString());

gitlab4j-models/src/main/java/org/gitlab4j/api/models/ImpersonationToken.java

@@ -49,6 +49,7 @@ public String toString() {
     private Long userId;
     private Boolean revoked;
     private String name;
+    private String description;
     private Long id;
     private Date createdAt;
     private Date lastUsedAt;
@@ -105,6 +106,14 @@ public void setName(String name) {
         this.name = name;
     }
 
+    public String getDescription() {
+        return description;
+    }
+
+    public void setDescription(String description) {
+        this.description = description;
+    }
+
     public Long getId() {
         return id;
     }

gitlab4j-models/src/main/java/org/gitlab4j/api/models/PersonalAccessToken.java

@@ -15,6 +15,7 @@ public class PersonalAccessToken implements Serializable {
     private Long userId;
     private List<Constants.ProjectAccessTokenScope> scopes;
     private String name;
+    private String description;
 
     @JsonSerialize(using = JacksonJson.DateOnlySerializer.class)
     private Date expiresAt;
@@ -50,6 +51,14 @@ public void setName(String name) {
         this.name = name;
     }
 
+    public String getDescription() {
+        return description;
+    }
+
+    public void setDescription(String description) {
+        this.description = description;
+    }
+
     public Date getExpiresAt() {
         return expiresAt;
     }

gitlab4j-models/src/test/resources/org/gitlab4j/models/impersonation-token.json

@@ -7,6 +7,7 @@
   "revoked" : true,
   "token" : "ZcZRpLeEuQRprkRjYydY",
   "name" : "mytoken2",
+  "description": "Test Token description",
   "created_at" : "2017-03-17T17:19:28.697Z",
   "last_used_at": "2018-03-17T17:19:28.697Z",
   "id" : 3,

gitlab4j-models/src/test/resources/org/gitlab4j/models/personal-access-token.json

@@ -1,6 +1,7 @@
 {
     "id": 42,
     "name": "Rotated Token",
+    "description": "Test Token description",
     "revoked": false,
     "created_at": "2023-08-01T15:00:00Z",
     "scopes": ["api"],