From 988effb24a55b46dbf9436fb36c9ec4eabb9f514 Mon Sep 17 00:00:00 2001 From: AJ Emerich Date: Thu, 12 Feb 2026 18:02:03 +0100 Subject: [PATCH] docs(gitlab): add descriptions --- .../plugin/gitlab/AbstractGitLabTask.java | 20 +++++++++++++++---- .../kestra/plugin/gitlab/issues/Create.java | 17 ++++++++-------- .../kestra/plugin/gitlab/issues/Search.java | 15 +++++++------- .../plugin/gitlab/mergerequests/Create.java | 17 ++++++++-------- 4 files changed, 39 insertions(+), 30 deletions(-) diff --git a/src/main/java/io/kestra/plugin/gitlab/AbstractGitLabTask.java b/src/main/java/io/kestra/plugin/gitlab/AbstractGitLabTask.java index f01997e..ea50ebe 100644 --- a/src/main/java/io/kestra/plugin/gitlab/AbstractGitLabTask.java +++ b/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 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 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 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 apiPath = Property.ofValue("/api/v4/projects"); diff --git a/src/main/java/io/kestra/plugin/gitlab/issues/Create.java b/src/main/java/io/kestra/plugin/gitlab/issues/Create.java index 9f2d21c..5be9ffa 100644 --- a/src/main/java/io/kestra/plugin/gitlab/issues/Create.java +++ b/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 { - @Schema(title = "Issue title") + @Schema(title = "Issue title", description = "Title text for the new issue (required).") @NotNull private Property title; - @Schema(title = "Issue description") + @Schema(title = "Issue description", description = "Optional Markdown or text body for the issue.") private Property 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> 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; } -} \ No newline at end of file +} diff --git a/src/main/java/io/kestra/plugin/gitlab/issues/Search.java b/src/main/java/io/kestra/plugin/gitlab/issues/Search.java index 95f0e13..9636fc8 100644 --- a/src/main/java/io/kestra/plugin/gitlab/issues/Search.java +++ b/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 { - @Schema(title = "Search query") + @Schema(title = "Search query", description = "Free-text query matched against issue title and description.") private Property 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 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> labels; @Override @@ -126,10 +125,10 @@ public static class Output implements io.kestra.core.models.tasks.Output { @Schema(title = "Found issues") private List> 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; } } diff --git a/src/main/java/io/kestra/plugin/gitlab/mergerequests/Create.java b/src/main/java/io/kestra/plugin/gitlab/mergerequests/Create.java index c4dd756..a8f58ea 100644 --- a/src/main/java/io/kestra/plugin/gitlab/mergerequests/Create.java +++ b/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 { - @Schema(title = "Merge request title") + @Schema(title = "Merge request title", description = "Title shown on the merge request (required).") @NotNull private Property title; - @Schema(title = "Source branch") + @Schema(title = "Source branch", description = "Branch name to merge from (required).") @NotNull private Property sourceBranch; - @Schema(title = "Target branch") + @Schema(title = "Target branch", description = "Branch name to merge into (required).") @NotNull private Property targetBranch; - @Schema(title = "Merge request description") + @Schema(title = "Merge request description", description = "Optional Markdown or text body for the merge request.") private Property 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; }