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 c5b1baa9ada..3027564db5b 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 1ebb17b249f..0d4e40616a1 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 344d54c878f..b2478323874 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 8ec0d53a795..c28ba02dbb7 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 3ea324186d7..8d9363fe916 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 46bd56646b1..eb4a1084e20 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 1f256911050..97837dfc248 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 2bb8f1b76b0..7ae046a9b07 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