From 7707ad7a0a6cda66036bd0eec2dead95d8664326 Mon Sep 17 00:00:00 2001 From: stevegt Date: Thu, 31 May 2018 04:13:55 -0700 Subject: [PATCH] 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 --- public/swagger.v1.json | 41 +++++++++++++++++++++++++++++++ routers/api/v1/swagger/issue.go | 10 ++++++++ routers/api/v1/swagger/key.go | 6 +++++ routers/api/v1/swagger/misc.go | 1 + routers/api/v1/swagger/options.go | 1 + routers/api/v1/swagger/org.go | 4 +++ routers/api/v1/swagger/repo.go | 16 ++++++++++++ routers/api/v1/swagger/user.go | 3 +++ 8 files changed, 82 insertions(+) diff --git a/public/swagger.v1.json b/public/swagger.v1.json index c5b1baa9ad..3027564db5 100644 --- 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" }, 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