Correct swagger annotations for enums, status codes, and notification state

modules/structs/activity.go

@@ -12,7 +12,7 @@ type Activity struct {
 	UserID int64 `json:"user_id"` // Receiver user
 	// the type of action
 	//
-	// enum: create_repo,rename_repo,star_repo,watch_repo,commit_repo,create_issue,create_pull_request,transfer_repo,push_tag,comment_issue,merge_pull_request,close_issue,reopen_issue,close_pull_request,reopen_pull_request,delete_tag,delete_branch,mirror_sync_push,mirror_sync_create,mirror_sync_delete,approve_pull_request,reject_pull_request,comment_pull,publish_release,pull_review_dismissed,pull_request_ready_for_review,auto_merge_pull_request
+	// enum: ["create_repo","rename_repo","star_repo","watch_repo","commit_repo","create_issue","create_pull_request","transfer_repo","push_tag","comment_issue","merge_pull_request","close_issue","reopen_issue","close_pull_request","reopen_pull_request","delete_tag","delete_branch","mirror_sync_push","mirror_sync_create","mirror_sync_delete","approve_pull_request","reject_pull_request","comment_pull","publish_release","pull_review_dismissed","pull_request_ready_for_review","auto_merge_pull_request"]
 	OpType string `json:"op_type"`
 	// The ID of the user who performed the action
 	ActUserID int64 `json:"act_user_id"`

modules/structs/hook.go

@@ -51,7 +51,7 @@ type CreateHookOptionConfig map[string]string
 // CreateHookOption options when create a hook
 type CreateHookOption struct {
 	// required: true
-	// enum: dingtalk,discord,gitea,gogs,msteams,slack,telegram,feishu,wechatwork,packagist
+	// enum: ["dingtalk","discord","gitea","gogs","msteams","slack","telegram","feishu","wechatwork","packagist"]
 	// The type of the webhook to create
 	Type string `json:"type" binding:"Required"`
 	// required: true

modules/structs/issue.go

@@ -14,17 +14,20 @@ import (
 )
 
 // StateType issue state type
+//
+// swagger:enum StateType
 type StateType string
 
 const (
 	// StateOpen pr is opened
 	StateOpen StateType = "open"
 	// StateClosed pr is closed
 	StateClosed StateType = "closed"
-	// StateAll is all
-	StateAll StateType = "all"
 )
 
+// StateAll is a query parameter filter value, not a valid object state.
+const StateAll = "all"
+
 // PullRequestMeta PR info if an issue is a PR
 type PullRequestMeta struct {
 	HasMerged        bool       `json:"merged"`
@@ -58,15 +61,11 @@ type Issue struct {
 	Labels           []*Label      `json:"labels"`
 	Milestone        *Milestone    `json:"milestone"`
 	// deprecated
-	Assignee  *User   `json:"assignee"`
-	Assignees []*User `json:"assignees"`
-	// Whether the issue is open or closed
-	//
-	// type: string
-	// enum: open,closed
-	State    StateType `json:"state"`
-	IsLocked bool      `json:"is_locked"`
-	Comments int       `json:"comments"`
+	Assignee  *User     `json:"assignee"`
+	Assignees []*User   `json:"assignees"`
+	State     StateType `json:"state"`
+	IsLocked  bool      `json:"is_locked"`
+	Comments  int       `json:"comments"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`
 	// swagger:strfmt date-time
@@ -132,6 +131,8 @@ type IssueDeadline struct {
 }
 
 // IssueFormFieldType defines issue form field type, can be "markdown", "textarea", "input", "dropdown" or "checkboxes"
+//
+// swagger:enum IssueFormFieldType
 type IssueFormFieldType string
 
 const (
@@ -168,7 +169,8 @@ func (iff IssueFormField) VisibleInContent() bool {
 }
 
 // IssueFormFieldVisible defines issue form field visible
-// swagger:model
+//
+// swagger:enum IssueFormFieldVisible
 type IssueFormFieldVisible string
 
 const (

modules/structs/issue_milestone.go

@@ -40,7 +40,7 @@ type CreateMilestoneOption struct {
 	// swagger:strfmt date-time
 	// Deadline is the due date for the milestone
 	Deadline *time.Time `json:"due_on"`
-	// enum: open,closed
+	// enum: ["open","closed"]
 	// State indicates the initial state of the milestone
 	State string `json:"state"`
 }
@@ -52,6 +52,7 @@ type EditMilestoneOption struct {
 	// Description provides updated details about the milestone
 	Description *string `json:"description"`
 	// State indicates the updated state of the milestone
+	// enum: ["open","closed"]
 	State *string `json:"state"`
 	// Deadline is the updated due date for the milestone
 	Deadline *time.Time `json:"due_on"`

modules/structs/notifications.go

@@ -40,7 +40,7 @@ type NotificationSubject struct {
 	// Type indicates the type of the notification subject
 	Type NotifySubjectType `json:"type" binding:"In(Issue,Pull,Commit,Repository)"`
 	// State indicates the current state of the notification subject
-	State StateType `json:"state"`
+	State NotifySubjectStateType `json:"state"`
 }
 
 // NotificationCount number of unread notifications
@@ -49,7 +49,22 @@ type NotificationCount struct {
 	New int64 `json:"new"`
 }
 
+// NotifySubjectStateType represents the state of a notification subject
+// swagger:enum NotifySubjectStateType
+type NotifySubjectStateType string
+
+const (
+	// NotifySubjectStateOpen is an open subject
+	NotifySubjectStateOpen NotifySubjectStateType = "open"
+	// NotifySubjectStateClosed is a closed subject
+	NotifySubjectStateClosed NotifySubjectStateType = "closed"
+	// NotifySubjectStateMerged is a merged pull request
+	NotifySubjectStateMerged NotifySubjectStateType = "merged"
+)
+
 // NotifySubjectType represent type of notification subject
+//
+// swagger:enum NotifySubjectType
 type NotifySubjectType string
 
 const (

modules/structs/org.go

@@ -60,7 +60,7 @@ type CreateOrgOption struct {
 	// The location of the organization
 	Location string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public` (default), `limited` or `private`
-	// enum: public,limited,private
+	// enum: ["public","limited","private"]
 	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
 	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
@@ -79,7 +79,7 @@ type EditOrgOption struct {
 	// The location of the organization
 	Location *string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public`, `limited` or `private`
-	// enum: public,limited,private
+	// enum: ["public","limited","private"]
 	Visibility *string `json:"visibility" binding:"In(,public,limited,private)"`
 	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess *bool `json:"repo_admin_change_team_access"`

modules/structs/org_team.go

@@ -16,7 +16,7 @@ type Team struct {
 	Organization *Organization `json:"organization"`
 	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories bool `json:"includes_all_repositories"`
-	// enum: none,read,write,admin,owner
+	// enum: ["none","read","write","admin","owner"]
 	Permission string `json:"permission"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
@@ -35,7 +35,7 @@ type CreateTeamOption struct {
 	Description string `json:"description" binding:"MaxSize(255)"`
 	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories bool `json:"includes_all_repositories"`
-	// enum: read,write,admin
+	// enum: ["read","write","admin"]
 	Permission string `json:"permission"`
 	// example: ["repo.actions","repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.ext_wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
@@ -54,7 +54,7 @@ type EditTeamOption struct {
 	Description *string `json:"description" binding:"MaxSize(255)"`
 	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories *bool `json:"includes_all_repositories"`
-	// enum: read,write,admin
+	// enum: ["read","write","admin"]
 	Permission string `json:"permission"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.

modules/structs/pull_review.go

@@ -8,6 +8,8 @@ import (
 )
 
 // ReviewStateType review state type
+//
+// swagger:enum ReviewStateType
 type ReviewStateType string
 
 const (
@@ -21,10 +23,11 @@ const (
 	ReviewStateRequestChanges ReviewStateType = "REQUEST_CHANGES"
 	// ReviewStateRequestReview review is requested from user
 	ReviewStateRequestReview ReviewStateType = "REQUEST_REVIEW"
-	// ReviewStateUnknown state of pr is unknown
-	ReviewStateUnknown ReviewStateType = ""
 )
 
+// ReviewStateUnknown is an internal sentinel for unknown review state, not a valid API value.
+const ReviewStateUnknown = ""
+
 // PullReview represents a pull request review
 type PullReview struct {
 	ID                int64           `json:"id"`

modules/structs/repo.go

@@ -114,7 +114,7 @@ type Repository struct {
 	Internal                      bool             `json:"internal"`
 	MirrorInterval                string           `json:"mirror_interval"`
 	// ObjectFormatName of the underlying git repository
-	// enum: sha1,sha256
+	// enum: ["sha1","sha256"]
 	ObjectFormatName string `json:"object_format_name"`
 	// swagger:strfmt date-time
 	MirrorUpdated time.Time     `json:"mirror_updated"`
@@ -150,10 +150,10 @@ type CreateRepoOption struct {
 	// DefaultBranch of the repository (used when initializes and in template)
 	DefaultBranch string `json:"default_branch" binding:"GitRefName;MaxSize(100)"`
 	// TrustModel of the repository
-	// enum: default,collaborator,committer,collaboratorcommitter
+	// enum: ["default","collaborator","committer","collaboratorcommitter"]
 	TrustModel string `json:"trust_model"`
 	// ObjectFormatName of the underlying git repository, empty string for default (sha1)
-	// enum: sha1,sha256
+	// enum: ["sha1","sha256"]
 	ObjectFormatName string `json:"object_format_name" binding:"MaxSize(6)"`
 }
 
@@ -378,7 +378,7 @@ type MigrateRepoOptions struct {
 	// required: true
 	RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`
 
-	// enum: git,github,gitea,gitlab,gogs,onedev,gitbucket,codebase,codecommit
+	// enum: ["git","github","gitea","gitlab","gogs","onedev","gitbucket","codebase","codecommit"]
 	Service      string `json:"service"`
 	AuthUsername string `json:"auth_username"`
 	AuthPassword string `json:"auth_password"`

modules/structs/repo_collaborator.go

@@ -5,7 +5,7 @@ package structs
 
 // AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
-	// enum: read,write,admin
+	// enum: ["read","write","admin"]
 	// Permission level to grant the collaborator
 	Permission *string `json:"permission"`
 }

modules/structs/repo_file.go

@@ -72,7 +72,7 @@ type ChangeFileOperation struct {
 	// indicates what to do with the file: "create" for creating a new file, "update" for updating an existing file,
 	// "upload" for creating or updating a file, "rename" for renaming a file, and "delete" for deleting an existing file.
 	// required: true
-	// enum: create,update,upload,rename,delete
+	// enum: ["create","update","upload","rename","delete"]
 	Operation string `json:"operation" binding:"Required"`
 	// path to the existing or new file
 	// required: true

routers/api/v1/admin/runners.go

@@ -40,7 +40,7 @@ func ListRunners(ctx *context.APIContext) {
 	//   required: false
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunnersResponse"
+	//     "$ref": "#/responses/RunnerList"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -63,7 +63,7 @@ func GetRunner(ctx *context.APIContext) {
 	//   required: true
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -115,7 +115,7 @@ func UpdateRunner(ctx *context.APIContext) {
 	//     "$ref": "#/definitions/EditActionRunnerOption"
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":

routers/api/v1/api.go

@@ -11,11 +11,9 @@
 //
 //	Consumes:
 //	- application/json
-//	- text/plain
 //
 //	Produces:
 //	- application/json
-//	- text/html
 //
 //	Security:
 //	- BasicAuth :

routers/api/v1/org/action.go

@@ -492,7 +492,7 @@ func (Action) ListRunners(ctx *context.APIContext) {
 	//   required: false
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunnersResponse"
+	//     "$ref": "#/responses/RunnerList"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -520,7 +520,7 @@ func (Action) GetRunner(ctx *context.APIContext) {
 	//   required: true
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -582,7 +582,7 @@ func (Action) UpdateRunner(ctx *context.APIContext) {
 	//     "$ref": "#/definitions/EditActionRunnerOption"
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":

routers/api/v1/repo/action.go

@@ -561,7 +561,7 @@ func (Action) ListRunners(ctx *context.APIContext) {
 	//   required: false
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunnersResponse"
+	//     "$ref": "#/responses/RunnerList"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -594,7 +594,7 @@ func (Action) GetRunner(ctx *context.APIContext) {
 	//   required: true
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -666,7 +666,7 @@ func (Action) UpdateRunner(ctx *context.APIContext) {
 	//     "$ref": "#/definitions/EditActionRunnerOption"
 	// responses:
 	//   "200":
-	//     "$ref": "#/definitions/ActionRunner"
+	//     "$ref": "#/responses/Runner"
 	//   "400":
 	//     "$ref": "#/responses/error"
 	//   "404":
@@ -1192,7 +1192,7 @@ func GetWorkflowRun(ctx *context.APIContext) {
 	// - name: run
 	//   in: path
 	//   description: id of the run
-	//   type: string
+	//   type: integer
 	//   required: true
 	// responses:
 	//   "200":

routers/api/v1/repo/issue_reaction.go

@@ -175,7 +175,7 @@ func DeleteIssueCommentReaction(ctx *context.APIContext) {
 	//   schema:
 	//     "$ref": "#/definitions/EditReactionOption"
 	// responses:
-	//   "200":
+	//   "204":
 	//     "$ref": "#/responses/empty"
 	//   "403":
 	//     "$ref": "#/responses/forbidden"
@@ -248,8 +248,7 @@ func changeIssueCommentReaction(ctx *context.APIContext, form api.EditReactionOp
 			ctx.APIErrorInternal(err)
 			return
 		}
-		// ToDo respond 204
-		ctx.Status(http.StatusOK)
+		ctx.Status(http.StatusNoContent)
 	}
 }
 
@@ -408,7 +407,7 @@ func DeleteIssueReaction(ctx *context.APIContext) {
 	//   schema:
 	//     "$ref": "#/definitions/EditReactionOption"
 	// responses:
-	//   "200":
+	//   "204":
 	//     "$ref": "#/responses/empty"
 	//   "403":
 	//     "$ref": "#/responses/forbidden"
@@ -464,7 +463,6 @@ func changeIssueReaction(ctx *context.APIContext, form api.EditReactionOption, i
 			ctx.APIErrorInternal(err)
 			return
 		}
-		// ToDo respond 204
-		ctx.Status(http.StatusOK)
+		ctx.Status(http.StatusNoContent)
 	}
 }

routers/api/v1/repo/pull.go

@@ -898,6 +898,8 @@ func MergePullRequest(ctx *context.APIContext) {
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	//   "404":
 	//     "$ref": "#/responses/notFound"
 	//   "405":