add simple descriptions for swagger validate (#4087)

* Partial fix for #4010

Swagger needs a comment line above each swagger:response comment -- it
uses these to populate the description: fields.  Adding minimal text
for now on the way to getting swagger validate to pass.  Many standard
swagger client libraries will not work at all with gitea until validate
passes, so prioritizing that over better descriptions for now.

Signed-off-by: Steve Traugott <stevegt@t7a.org>

7 files changed, 41 insertions, 0 deletions

diff --git a/routers/api/v1/swagger/issue.go b/routers/api/v1/swagger/issue.go
index 1ebb17b249..0d4e40616a 100644
--- a/routers/api/v1/swagger/issue.go
+++ b/routers/api/v1/swagger/issue.go
@@ -8,60 +8,70 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// Issue
 // swagger:response Issue
 type swaggerResponseIssue struct {
 	// in:body
 	Body api.Issue `json:"body"`
 }
 
+// IssueList
 // swagger:response IssueList
 type swaggerResponseIssueList struct {
 	// in:body
 	Body []api.Issue `json:"body"`
 }
 
+// Comment
 // swagger:response Comment
 type swaggerResponseComment struct {
 	// in:body
 	Body api.Comment `json:"body"`
 }
 
+// CommentList
 // swagger:response CommentList
 type swaggerResponseCommentList struct {
 	// in:body
 	Body []api.Comment `json:"body"`
 }
 
+// Label
 // swagger:response Label
 type swaggerResponseLabel struct {
 	// in:body
 	Body api.Label `json:"body"`
 }
 
+// LabelList
 // swagger:response LabelList
 type swaggerResponseLabelList struct {
 	// in:body
 	Body []api.Label `json:"body"`
 }
 
+// Milestone
 // swagger:response Milestone
 type swaggerResponseMilestone struct {
 	// in:body
 	Body api.Milestone `json:"body"`
 }
 
+// MilestoneList
 // swagger:response MilestoneList
 type swaggerResponseMilestoneList struct {
 	// in:body
 	Body []api.Milestone `json:"body"`
 }
 
+// TrackedTime
 // swagger:response TrackedTime
 type swaggerResponseTrackedTime struct {
 	// in:body
 	Body api.TrackedTime `json:"body"`
 }
 
+// TrackedTimeList
 // swagger:response TrackedTimeList
 type swaggerResponseTrackedTimeList struct {
 	// in:body
diff --git a/routers/api/v1/swagger/key.go b/routers/api/v1/swagger/key.go
index 344d54c878..b247832387 100644
--- a/routers/api/v1/swagger/key.go
+++ b/routers/api/v1/swagger/key.go
@@ -8,36 +8,42 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// PublicKey
 // swagger:response PublicKey
 type swaggerResponsePublicKey struct {
 	// in:body
 	Body api.PublicKey `json:"body"`
 }
 
+// PublicKeyList
 // swagger:response PublicKeyList
 type swaggerResponsePublicKeyList struct {
 	// in:body
 	Body []api.PublicKey `json:"body"`
 }
 
+// GPGKey
 // swagger:response GPGKey
 type swaggerResponseGPGKey struct {
 	// in:body
 	Body api.GPGKey `json:"body"`
 }
 
+// GPGKeyList
 // swagger:response GPGKeyList
 type swaggerResponseGPGKeyList struct {
 	// in:body
 	Body []api.GPGKey `json:"body"`
 }
 
+// DeployKey
 // swagger:response DeployKey
 type swaggerResponseDeployKey struct {
 	// in:body
 	Body api.DeployKey `json:"body"`
 }
 
+// DeployKeyList
 // swagger:response DeployKeyList
 type swaggerResponseDeployKeyList struct {
 	// in:body
diff --git a/routers/api/v1/swagger/misc.go b/routers/api/v1/swagger/misc.go
index 8ec0d53a79..c28ba02dbb 100644
--- a/routers/api/v1/swagger/misc.go
+++ b/routers/api/v1/swagger/misc.go
@@ -8,6 +8,7 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// ServerVersion
 // swagger:response ServerVersion
 type swaggerResponseServerVersion struct {
 	// in:body
diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go
index 3ea324186d..8d9363fe91 100644
--- a/routers/api/v1/swagger/options.go
+++ b/routers/api/v1/swagger/options.go
@@ -12,6 +12,7 @@ import (
 // not actually a response, just a hack to get go-swagger to include definitions
 // of the various XYZOption structs
 
+// parameterBodies
 // swagger:response parameterBodies
 type swaggerParameterBodies struct {
 	AddCollaboratorOption api.AddCollaboratorOption
diff --git a/routers/api/v1/swagger/org.go b/routers/api/v1/swagger/org.go
index 46bd56646b..eb4a1084e2 100644
--- a/routers/api/v1/swagger/org.go
+++ b/routers/api/v1/swagger/org.go
@@ -8,24 +8,28 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// Organization
 // swagger:response Organization
 type swaggerResponseOrganization struct {
 	// in:body
 	Body api.Organization `json:"body"`
 }
 
+// OrganizationList
 // swagger:response OrganizationList
 type swaggerResponseOrganizationList struct {
 	// in:body
 	Body []api.Organization `json:"body"`
 }
 
+// Team
 // swagger:response Team
 type swaggerResponseTeam struct {
 	// in:body
 	Body api.Team `json:"body"`
 }
 
+// TeamList
 // swagger:response TeamList
 type swaggerResponseTeamList struct {
 	// in:body
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
index 1f25691105..97837dfc24 100644
--- a/routers/api/v1/swagger/repo.go
+++ b/routers/api/v1/swagger/repo.go
@@ -8,95 +8,111 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// Repository
 // swagger:response Repository
 type swaggerResponseRepository struct {
 	// in:body
 	Body api.Repository `json:"body"`
 }
 
+// RepositoryList
 // swagger:response RepositoryList
 type swaggerResponseRepositoryList struct {
 	// in:body
 	Body []api.Repository `json:"body"`
 }
 
+// Branch
 // swagger:response Branch
 type swaggerResponseBranch struct {
 	// in:body
 	Body api.Branch `json:"body"`
 }
 
+// BranchList
 // swagger:response BranchList
 type swaggerResponseBranchList struct {
 	// in:body
 	Body []api.Branch `json:"body"`
 }
 
+// Hook
 // swagger:response Hook
 type swaggerResponseHook struct {
 	// in:body
 	Body []api.Branch `json:"body"`
 }
 
+// HookList
 // swagger:response HookList
 type swaggerResponseHookList struct {
 	// in:body
 	Body []api.Branch `json:"body"`
 }
 
+// Release
 // swagger:response Release
 type swaggerResponseRelease struct {
 	// in:body
 	Body api.Release `json:"body"`
 }
 
+// ReleaseList
 // swagger:response ReleaseList
 type swaggerResponseReleaseList struct {
 	// in:body
 	Body []api.Release `json:"body"`
 }
 
+// PullRequest
 // swagger:response PullRequest
 type swaggerResponsePullRequest struct {
 	// in:body
 	Body api.PullRequest `json:"body"`
 }
 
+// PullRequestList
 // swagger:response PullRequestList
 type swaggerResponsePullRequestList struct {
 	// in:body
 	Body []api.PullRequest `json:"body"`
 }
 
+// Status
 // swagger:response Status
 type swaggerResponseStatus struct {
 	// in:body
 	Body api.Status `json:"body"`
 }
 
+// StatusList
 // swagger:response StatusList
 type swaggerResponseStatusList struct {
 	// in:body
 	Body []api.Status `json:"body"`
 }
 
+// WatchInfo
 // swagger:response WatchInfo
 type swaggerResponseWatchInfo struct {
 	// in:body
 	Body api.WatchInfo `json:"body"`
 }
 
+// SearchResults
 // swagger:response SearchResults
 type swaggerResponseSearchResults struct {
 	Body api.SearchResults `json:"body"`
 }
 
+// AttachmentList
 // swagger:response AttachmentList
 type swaggerResponseAttachmentList struct {
 	//in: body
 	Body []api.Attachment `json:"body"`
 }
 
+// Attachment
 // swagger:response Attachment
 type swaggerResponseAttachment struct {
 	//in: body
diff --git a/routers/api/v1/swagger/user.go b/routers/api/v1/swagger/user.go
index 2bb8f1b76b..7ae046a9b0 100644
--- a/routers/api/v1/swagger/user.go
+++ b/routers/api/v1/swagger/user.go
@@ -8,18 +8,21 @@ import (
 	api "code.gitea.io/sdk/gitea"
 )
 
+// User
 // swagger:response User
 type swaggerResponseUser struct {
 	// in:body
 	Body api.User `json:"body"`
 }
 
+// UserList
 // swagger:response UserList
 type swaggerResponseUserList struct {
 	// in:body
 	Body []api.User `json:"body"`
 }
 
+// EmailList
 // swagger:response EmailList
 type swaggerResponseEmailList struct {
 	// in:body