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 years ago · 7707ad7a0a
parent 728cc27284
commit 7707ad7a0a
8 changed files with 82 additions and 0 deletions
--- a/public/swagger.v1.json
+++ b/public/swagger.v1.json
@ -7376,11 +7376,13 @@
      "description": "AccessTokenList represents a list of API access token."
    },
    "Attachment": {
+      "description": "Attachment",
      "schema": {
        "$ref": "#/definitions/Attachment"
      }
    },
    "AttachmentList": {
+      "description": "AttachmentList",
      "schema": {
        "type": "array",
        "items": {
@ -7389,11 +7391,13 @@
      }
    },
    "Branch": {
+      "description": "Branch",
      "schema": {
        "$ref": "#/definitions/Branch"
      }
    },
    "BranchList": {
+      "description": "BranchList",
      "schema": {
        "type": "array",
        "items": {
@ -7402,11 +7406,13 @@
      }
    },
    "Comment": {
+      "description": "Comment",
      "schema": {
        "$ref": "#/definitions/Comment"
      }
    },
    "CommentList": {
+      "description": "CommentList",
      "schema": {
        "type": "array",
        "items": {
@ -7415,11 +7421,13 @@
      }
    },
    "DeployKey": {
+      "description": "DeployKey",
      "schema": {
        "$ref": "#/definitions/DeployKey"
      }
    },
    "DeployKeyList": {
+      "description": "DeployKeyList",
      "schema": {
        "type": "array",
        "items": {
@ -7428,6 +7436,7 @@
      }
    },
    "EmailList": {
+      "description": "EmailList",
      "schema": {
        "type": "array",
        "items": {
@ -7436,11 +7445,13 @@
      }
    },
    "GPGKey": {
+      "description": "GPGKey",
      "schema": {
        "$ref": "#/definitions/GPGKey"
      }
    },
    "GPGKeyList": {
+      "description": "GPGKeyList",
      "schema": {
        "type": "array",
        "items": {
@ -7449,6 +7460,7 @@
      }
    },
    "Hook": {
+      "description": "Hook",
      "schema": {
        "type": "array",
        "items": {
@ -7457,6 +7469,7 @@
      }
    },
    "HookList": {
+      "description": "HookList",
      "schema": {
        "type": "array",
        "items": {
@ -7465,11 +7478,13 @@
      }
    },
    "Issue": {
+      "description": "Issue",
      "schema": {
        "$ref": "#/definitions/Issue"
      }
    },
    "IssueList": {
+      "description": "IssueList",
      "schema": {
        "type": "array",
        "items": {
@ -7478,11 +7493,13 @@
      }
    },
    "Label": {
+      "description": "Label",
      "schema": {
        "$ref": "#/definitions/Label"
      }
    },
    "LabelList": {
+      "description": "LabelList",
      "schema": {
        "type": "array",
        "items": {
@ -7494,11 +7511,13 @@
      "description": "MarkdownRender is a rendered markdown document"
    },
    "Milestone": {
+      "description": "Milestone",
      "schema": {
        "$ref": "#/definitions/Milestone"
      }
    },
    "MilestoneList": {
+      "description": "MilestoneList",
      "schema": {
        "type": "array",
        "items": {
@ -7507,11 +7526,13 @@
      }
    },
    "Organization": {
+      "description": "Organization",
      "schema": {
        "$ref": "#/definitions/Organization"
      }
    },
    "OrganizationList": {
+      "description": "OrganizationList",
      "schema": {
        "type": "array",
        "items": {
@ -7520,11 +7541,13 @@
      }
    },
    "PublicKey": {
+      "description": "PublicKey",
      "schema": {
        "$ref": "#/definitions/PublicKey"
      }
    },
    "PublicKeyList": {
+      "description": "PublicKeyList",
      "schema": {
        "type": "array",
        "items": {
@ -7533,11 +7556,13 @@
      }
    },
    "PullRequest": {
+      "description": "PullRequest",
      "schema": {
        "$ref": "#/definitions/PullRequest"
      }
    },
    "PullRequestList": {
+      "description": "PullRequestList",
      "schema": {
        "type": "array",
        "items": {
@ -7546,11 +7571,13 @@
      }
    },
    "Release": {
+      "description": "Release",
      "schema": {
        "$ref": "#/definitions/Release"
      }
    },
    "ReleaseList": {
+      "description": "ReleaseList",
      "schema": {
        "type": "array",
        "items": {
@ -7559,11 +7586,13 @@
      }
    },
    "Repository": {
+      "description": "Repository",
      "schema": {
        "$ref": "#/definitions/Repository"
      }
    },
    "RepositoryList": {
+      "description": "RepositoryList",
      "schema": {
        "type": "array",
        "items": {
@ -7572,6 +7601,7 @@
      }
    },
    "SearchResults": {
+      "description": "SearchResults",
      "schema": {
        "$ref": "#/definitions/SearchResults"
      },
@ -7580,16 +7610,19 @@
      }
    },
    "ServerVersion": {
+      "description": "ServerVersion",
      "schema": {
        "$ref": "#/definitions/ServerVersion"
      }
    },
    "Status": {
+      "description": "Status",
      "schema": {
        "$ref": "#/definitions/Status"
      }
    },
    "StatusList": {
+      "description": "StatusList",
      "schema": {
        "type": "array",
        "items": {
@ -7598,11 +7631,13 @@
      }
    },
    "Team": {
+      "description": "Team",
      "schema": {
        "$ref": "#/definitions/Team"
      }
    },
    "TeamList": {
+      "description": "TeamList",
      "schema": {
        "type": "array",
        "items": {
@ -7611,11 +7646,13 @@
      }
    },
    "TrackedTime": {
+      "description": "TrackedTime",
      "schema": {
        "$ref": "#/definitions/TrackedTime"
      }
    },
    "TrackedTimeList": {
+      "description": "TrackedTimeList",
      "schema": {
        "type": "array",
        "items": {
@ -7624,11 +7661,13 @@
      }
    },
    "User": {
+      "description": "User",
      "schema": {
        "$ref": "#/definitions/User"
      }
    },
    "UserList": {
+      "description": "UserList",
      "schema": {
        "type": "array",
        "items": {
@ -7637,6 +7676,7 @@
      }
    },
    "WatchInfo": {
+      "description": "WatchInfo",
      "schema": {
        "$ref": "#/definitions/WatchInfo"
      }
@ -7670,6 +7710,7 @@
      "description": "APINotFound is a not found empty response"
    },
    "parameterBodies": {
+      "description": "parameterBodies",
      "schema": {
        "$ref": "#/definitions/EditAttachmentOptions"
      },
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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