From bff5c00b804936a1d03c5335d99da180a861b8cf Mon Sep 17 00:00:00 2001 From: Robert Wolff Date: Sat, 7 Mar 2026 23:16:20 +0100 Subject: [PATCH] feat(api): more verbose error messages and swagger comments for posting issue comments (#11368) Closes: #11364 Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/11368 Reviewed-by: Cyborus Co-authored-by: Robert Wolff Co-committed-by: Robert Wolff --- modules/structs/issue_comment.go | 33 +++++++++++++++++++++-------- services/issue/issue.go | 4 ++-- templates/swagger/v1_json.tmpl | 14 ++++++++++++ tests/integration/api_issue_test.go | 2 +- 4 files changed, 41 insertions(+), 12 deletions(-) diff --git a/modules/structs/issue_comment.go b/modules/structs/issue_comment.go index 9ecb4a1789..766442374d 100644 --- a/modules/structs/issue_comment.go +++ b/modules/structs/issue_comment.go @@ -9,33 +9,48 @@ import ( // Comment represents a comment on a commit or issue type Comment struct { - ID int64 `json:"id"` - HTMLURL string `json:"html_url"` - PRURL string `json:"pull_request_url"` - IssueURL string `json:"issue_url"` - Poster *User `json:"user"` - OriginalAuthor string `json:"original_author"` - OriginalAuthorID int64 `json:"original_author_id"` - Body string `json:"body"` - Attachments []*Attachment `json:"assets"` + // The identifier of the comment + ID int64 `json:"id"` + // The HTML URL of the comment + HTMLURL string `json:"html_url"` + // The HTML URL of the pull request if the comment is posted on a pull request, else empty string + PRURL string `json:"pull_request_url"` + // The HTML URL of the issue if the comment is posted on an issue, else empty string + IssueURL string `json:"issue_url"` + // The user that posted the comment if it was posted locally + Poster *User `json:"user"` + // The original author that posted the comment if it was not posted locally, else empty string + OriginalAuthor string `json:"original_author"` + // The ID of the original author that posted the comment if it was not posted locally, else 0 + OriginalAuthorID int64 `json:"original_author_id"` + // The body of the comment + Body string `json:"body"` + // The attachments to the comment + Attachments []*Attachment `json:"assets"` + // The time of the comment's creation // swagger:strfmt date-time Created time.Time `json:"created_at"` + // The time of the comment's update // swagger:strfmt date-time Updated time.Time `json:"updated_at"` } // CreateIssueCommentOption options for creating a comment on an issue type CreateIssueCommentOption struct { + // The body of the comment // required:true Body string `json:"body" binding:"Required"` + // The time of the comment's update, needs admin or repository owner permission // swagger:strfmt date-time Updated *time.Time `json:"updated_at"` } // EditIssueCommentOption options for editing a comment type EditIssueCommentOption struct { + // The body of the comment // required: true Body string `json:"body" binding:"Required"` + // The time of the comment's update, needs admin or repository owner permission // swagger:strfmt date-time Updated *time.Time `json:"updated_at"` } diff --git a/services/issue/issue.go b/services/issue/issue.go index 9dfbd903b6..7a65d87cd4 100644 --- a/services/issue/issue.go +++ b/services/issue/issue.go @@ -342,13 +342,13 @@ func SetIssueUpdateDate(ctx context.Context, issue *issues_model.Issue, updated return err } if !perm.IsAdmin() && !perm.IsOwner() { - return errors.New("user needs to have admin or owner right") + return errors.New("user needs to have admin or repository owner right to set an update date") } // A simple guard against potential inconsistent calls updatedUnix := timeutil.TimeStamp(updated.Unix()) if updatedUnix < issue.CreatedUnix || updatedUnix > timeutil.TimeStampNow() { - return errors.New("unallowed update date") + return errors.New("unallowed update date, because given date must be between issue creation date and now") } issue.UpdatedUnix = updatedUnix diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index 11bde671df..d72142016a 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -23177,6 +23177,7 @@ "type": "object", "properties": { "assets": { + "description": "The attachments to the comment", "type": "array", "items": { "$ref": "#/definitions/Attachment" @@ -23184,41 +23185,50 @@ "x-go-name": "Attachments" }, "body": { + "description": "The body of the comment", "type": "string", "x-go-name": "Body" }, "created_at": { + "description": "The time of the comment's creation", "type": "string", "format": "date-time", "x-go-name": "Created" }, "html_url": { + "description": "The HTML URL of the comment", "type": "string", "x-go-name": "HTMLURL" }, "id": { + "description": "The identifier of the comment", "type": "integer", "format": "int64", "x-go-name": "ID" }, "issue_url": { + "description": "The HTML URL of the issue if the comment is posted on an issue, else empty string", "type": "string", "x-go-name": "IssueURL" }, "original_author": { + "description": "The original author that posted the comment if it was not posted locally, else empty string", "type": "string", "x-go-name": "OriginalAuthor" }, "original_author_id": { + "description": "The ID of the original author that posted the comment if it was not posted locally, else 0", "type": "integer", "format": "int64", "x-go-name": "OriginalAuthorID" }, "pull_request_url": { + "description": "The HTML URL of the pull request if the comment is posted on a pull request, else empty string", "type": "string", "x-go-name": "PRURL" }, "updated_at": { + "description": "The time of the comment's update", "type": "string", "format": "date-time", "x-go-name": "Updated" @@ -23886,10 +23896,12 @@ ], "properties": { "body": { + "description": "The body of the comment", "type": "string", "x-go-name": "Body" }, "updated_at": { + "description": "The time of the comment's update, needs admin or repository owner permission", "type": "string", "format": "date-time", "x-go-name": "Updated" @@ -25103,10 +25115,12 @@ ], "properties": { "body": { + "description": "The body of the comment", "type": "string", "x-go-name": "Body" }, "updated_at": { + "description": "The time of the comment's update, needs admin or repository owner permission", "type": "string", "format": "date-time", "x-go-name": "Updated" diff --git a/tests/integration/api_issue_test.go b/tests/integration/api_issue_test.go index 3f57e31757..6267065602 100644 --- a/tests/integration/api_issue_test.go +++ b/tests/integration/api_issue_test.go @@ -418,7 +418,7 @@ func TestAPIEditIssueAutoDate(t *testing.T) { var apiError api.APIError DecodeJSON(t, resp, &apiError) - assert.Equal(t, "user needs to have admin or owner right", apiError.Message) + assert.Equal(t, "user needs to have admin or repository owner right to set an update date", apiError.Message) }) }