docs(gitlab): add descriptions

Author: aj-emerich

src/main/java/io/kestra/plugin/gitlab/AbstractGitLabTask.java

@@ -21,19 +21,31 @@
 @NoArgsConstructor
 public abstract class AbstractGitLabTask extends Task {
 
-    @Schema(title = "GitLab host name", description = "The host name of the GitLab instance.")
+    @Schema(
+        title = "GitLab API base URL",
+        description = "Base URL of the GitLab instance; defaults to `https://gitlab.com`. Override for self-hosted installations."
+    )
     @Builder.Default
     private Property<String> url = Property.ofValue("https://gitlab.com");
 
-    @Schema(title = "Personal, Project or Group Access Token", description = "GitLab Personal, Project or Group Access Token. More information on the [GitLab documentation](https://docs.gitlab.com/api/rest/authentication/).")
+    @Schema(
+        title = "Access token used for API calls",
+        description = "GitLab Personal/Project/Group Access Token sent as the PRIVATE-TOKEN header; requires scopes that cover the requested API operations. See the [GitLab Authentication docs](https://docs.gitlab.com/api/rest/authentication/)."
+    )
     @NotNull
     private Property<String> token;
 
-    @Schema(title = "Project ID", description = "The global ID or URL-encoded path of the project.")
+    @Schema(
+        title = "Project ID or path",
+        description = "Numeric project ID or URL-encoded project path rendered from the context to build API endpoints."
+    )
     @NotNull
     private Property<String> projectId;
 
-    @Schema(title = "API Path", description = "Custom API path for GitLab API endpoints")
+    @Schema(
+        title = "Projects API path",
+        description = "Projects API prefix appended before the project ID; defaults to `/api/v4/projects`. Override when fronting GitLab with a proxy or custom base path."
+    )
     @Builder.Default
     private Property<String> apiPath = Property.ofValue("/api/v4/projects");
 

src/main/java/io/kestra/plugin/gitlab/issues/Create.java

@@ -26,9 +26,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Create a GitLab issue.",
-    description = "Create a new issue in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
+    title = "Create issue in a project",
+    description = "Creates an issue through the GitLab REST API for the specified project. Requires `projectId`, `token`, and `title`; description and labels are optional. Supports custom `url` and `apiPath` for self-hosted GitLab and renders templated values before sending."
 )
 @Plugin(examples = {
     @Example(
@@ -71,14 +70,14 @@
 })
 public class Create extends AbstractGitLabTask implements RunnableTask<Create.Output> {
 
-    @Schema(title = "Issue title")
+    @Schema(title = "Issue title", description = "Title text for the new issue (required).")
     @NotNull
     private Property<String> title;
 
-    @Schema(title = "Issue description")
+    @Schema(title = "Issue description", description = "Optional Markdown or text body for the issue.")
     private Property<String> issueDescription;
 
-    @Schema(title = "Labels to assign to the issue")
+    @Schema(title = "Labels to assign to the issue", description = "Rendered list of labels applied to the issue.")
     private Property<List<String>> labels;
 
     @Override
@@ -123,10 +122,10 @@ public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(title = "Issue ID")
         private String issueId;
 
-        @Schema(title = "Issue URL")
+        @Schema(title = "Issue URL", description = "Web URL of the created issue.")
         private String webUrl;
 
-        @Schema(title = "HTTP status code")
+        @Schema(title = "HTTP status code", description = "HTTP response code from the GitLab API.")
         private Integer statusCode;
     }
-}
+}

src/main/java/io/kestra/plugin/gitlab/issues/Search.java

@@ -25,9 +25,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Search GitLab issues.",
-    description = "Search for issues in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
+    title = "Search issues in a project",
+    description = "Queries GitLab issues for the target project via the REST API. Requires `projectId` and `token`; `state` defaults to `opened`. Supports custom `url` and `apiPath` for self-hosted GitLab and renders templated values before the request."
 )
 @Plugin(examples = {
     @Example(
@@ -73,14 +72,14 @@
 })
 public class Search extends AbstractGitLabTask implements RunnableTask<Search.Output> {
 
-    @Schema(title = "Search query")
+    @Schema(title = "Search query", description = "Free-text query matched against issue title and description.")
     private Property<String> search;
 
-    @Schema(title = "Issue state", description = "opened, closed or all")
+    @Schema(title = "Issue state", description = "Filter by state: opened, closed, or all; defaults to opened when not provided.")
     @Builder.Default
     private Property<String> state = Property.ofValue("opened");
 
-    @Schema(title = "Labels to filter by")
+    @Schema(title = "Labels to filter by", description = "Labels rendered from the context and comma-joined for the GitLab API.")
     private Property<List<String>> labels;
 
     @Override
@@ -126,10 +125,10 @@ public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(title = "Found issues")
         private List<Map<String, Object>> issues;
 
-        @Schema(title = "Number of issues found")
+        @Schema(title = "Number of issues found", description = "Count of issues returned by the request.")
         private Integer count;
 
-        @Schema(title = "HTTP status code")
+        @Schema(title = "HTTP status code", description = "HTTP response code from the GitLab API.")
         private Integer statusCode;
     }
 }

src/main/java/io/kestra/plugin/gitlab/mergerequests/Create.java

@@ -25,9 +25,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Create a GitLab merge request.",
-    description = "Create a new merge request in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
+    title = "Open a project merge request",
+    description = "Creates a merge request through the GitLab REST API for the target project. Requires `projectId`, `token`, `sourceBranch`, `targetBranch`, and `title`; description is optional. Supports custom `url` and `apiPath` for self-hosted GitLab and renders templated values before sending."
 )
 @Plugin(
     examples = {
@@ -73,19 +72,19 @@
 )
 public class Create extends AbstractGitLabTask implements RunnableTask<Create.Output> {
 
-    @Schema(title = "Merge request title")
+    @Schema(title = "Merge request title", description = "Title shown on the merge request (required).")
     @NotNull
     private Property<String> title;
 
-    @Schema(title = "Source branch")
+    @Schema(title = "Source branch", description = "Branch name to merge from (required).")
     @NotNull
     private Property<String> sourceBranch;
 
-    @Schema(title = "Target branch")
+    @Schema(title = "Target branch", description = "Branch name to merge into (required).")
     @NotNull
     private Property<String> targetBranch;
 
-    @Schema(title = "Merge request description")
+    @Schema(title = "Merge request description", description = "Optional Markdown or text body for the merge request.")
     private Property<String> mergeRequestDescription;
 
     @Override
@@ -132,10 +131,10 @@ public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(title = "Merge Request ID")
         private String mergeReqID;
 
-        @Schema(title = "Merge Request URL")
+        @Schema(title = "Merge Request URL", description = "Web URL of the created merge request.")
         private String webUrl;
 
-        @Schema(title = "HTTP status code")
+        @Schema(title = "HTTP status code", description = "HTTP response code from the GitLab API.")
         private Integer statusCode;
     }