Update swagger documentation (#2899)

* Update swagger documentation

Add docs for missing endpoints
Add documentation for request parameters
Make parameter naming consistent
Fix response documentation

* Restore delete comments

7 files changed, 353 insertions, 0 deletions

diff --git a/routers/api/v1/swagger/issue.go b/routers/api/v1/swagger/issue.go
new file mode 100644
index 0000000000..1ebb17b249
--- /dev/null
+++ b/routers/api/v1/swagger/issue.go
@@ -0,0 +1,69 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Issue
+type swaggerResponseIssue struct {
+	// in:body
+	Body api.Issue `json:"body"`
+}
+
+// swagger:response IssueList
+type swaggerResponseIssueList struct {
+	// in:body
+	Body []api.Issue `json:"body"`
+}
+
+// swagger:response Comment
+type swaggerResponseComment struct {
+	// in:body
+	Body api.Comment `json:"body"`
+}
+
+// swagger:response CommentList
+type swaggerResponseCommentList struct {
+	// in:body
+	Body []api.Comment `json:"body"`
+}
+
+// swagger:response Label
+type swaggerResponseLabel struct {
+	// in:body
+	Body api.Label `json:"body"`
+}
+
+// swagger:response LabelList
+type swaggerResponseLabelList struct {
+	// in:body
+	Body []api.Label `json:"body"`
+}
+
+// swagger:response Milestone
+type swaggerResponseMilestone struct {
+	// in:body
+	Body api.Milestone `json:"body"`
+}
+
+// swagger:response MilestoneList
+type swaggerResponseMilestoneList struct {
+	// in:body
+	Body []api.Milestone `json:"body"`
+}
+
+// swagger:response TrackedTime
+type swaggerResponseTrackedTime struct {
+	// in:body
+	Body api.TrackedTime `json:"body"`
+}
+
+// swagger:response TrackedTimeList
+type swaggerResponseTrackedTimeList struct {
+	// in:body
+	Body []api.TrackedTime `json:"body"`
+}
diff --git a/routers/api/v1/swagger/key.go b/routers/api/v1/swagger/key.go
new file mode 100644
index 0000000000..344d54c878
--- /dev/null
+++ b/routers/api/v1/swagger/key.go
@@ -0,0 +1,45 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response PublicKey
+type swaggerResponsePublicKey struct {
+	// in:body
+	Body api.PublicKey `json:"body"`
+}
+
+// swagger:response PublicKeyList
+type swaggerResponsePublicKeyList struct {
+	// in:body
+	Body []api.PublicKey `json:"body"`
+}
+
+// swagger:response GPGKey
+type swaggerResponseGPGKey struct {
+	// in:body
+	Body api.GPGKey `json:"body"`
+}
+
+// swagger:response GPGKeyList
+type swaggerResponseGPGKeyList struct {
+	// in:body
+	Body []api.GPGKey `json:"body"`
+}
+
+// swagger:response DeployKey
+type swaggerResponseDeployKey struct {
+	// in:body
+	Body api.DeployKey `json:"body"`
+}
+
+// swagger:response DeployKeyList
+type swaggerResponseDeployKeyList struct {
+	// in:body
+	Body []api.DeployKey `json:"body"`
+}
diff --git a/routers/api/v1/swagger/misc.go b/routers/api/v1/swagger/misc.go
new file mode 100644
index 0000000000..8ec0d53a79
--- /dev/null
+++ b/routers/api/v1/swagger/misc.go
@@ -0,0 +1,15 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response ServerVersion
+type swaggerResponseServerVersion struct {
+	// in:body
+	Body api.ServerVersion `json:"body"`
+}
diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go
new file mode 100644
index 0000000000..31251eb3e2
--- /dev/null
+++ b/routers/api/v1/swagger/options.go
@@ -0,0 +1,66 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	"code.gitea.io/gitea/modules/auth"
+	api "code.gitea.io/sdk/gitea"
+)
+
+// not actually a response, just a hack to get go-swagger to include definitions
+// of the various XYZOption structs
+
+// swagger:response parameterBodies
+type swaggerParameterBodies struct {
+	AddCollaboratorOption api.AddCollaboratorOption
+
+	CreateEmailOption api.CreateEmailOption
+	DeleteEmailOption api.DeleteEmailOption
+
+	CreateHookOption api.CreateHookOption
+	EditHookOption   api.EditHookOption
+
+	CreateIssueOption api.CreateIssueOption
+	EditIssueOption   api.EditIssueOption
+
+	CreateIssueCommentOption api.CreateIssueCommentOption
+	EditIssueCommentOption   api.EditIssueCommentOption
+
+	IssueLabelsOption api.IssueLabelsOption
+
+	CreateKeyOption api.CreateKeyOption
+
+	CreateLabelOption api.CreateLabelOption
+	EditLabelOption   api.EditLabelOption
+
+	MarkdownOption api.MarkdownOption
+
+	CreateMilestoneOption api.CreateMilestoneOption
+	EditMilestoneOption   api.EditMilestoneOption
+
+	CreateOrgOption api.CreateOrgOption
+	EditOrgOption   api.EditOrgOption
+
+	CreatePullRequestOption api.CreatePullRequestOption
+	EditPullRequestOption   api.EditPullRequestOption
+
+	CreateReleaseOption api.CreateReleaseOption
+	EditReleaseOption   api.EditReleaseOption
+
+	CreateRepoOption api.CreateRepoOption
+	CreateForkOption api.CreateForkOption
+
+	CreateStatusOption api.CreateStatusOption
+
+	CreateTeamOption api.CreateTeamOption
+	EditTeamOption   api.EditTeamOption
+
+	AddTimeOption api.AddTimeOption
+
+	CreateUserOption api.CreateUserOption
+	EditUserOption   api.EditUserOption
+
+	MigrateRepoForm auth.MigrateRepoForm
+}
diff --git a/routers/api/v1/swagger/org.go b/routers/api/v1/swagger/org.go
new file mode 100644
index 0000000000..46bd56646b
--- /dev/null
+++ b/routers/api/v1/swagger/org.go
@@ -0,0 +1,33 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Organization
+type swaggerResponseOrganization struct {
+	// in:body
+	Body api.Organization `json:"body"`
+}
+
+// swagger:response OrganizationList
+type swaggerResponseOrganizationList struct {
+	// in:body
+	Body []api.Organization `json:"body"`
+}
+
+// swagger:response Team
+type swaggerResponseTeam struct {
+	// in:body
+	Body api.Team `json:"body"`
+}
+
+// swagger:response TeamList
+type swaggerResponseTeamList struct {
+	// in:body
+	Body []api.Team `json:"body"`
+}
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
new file mode 100644
index 0000000000..703f7d18dd
--- /dev/null
+++ b/routers/api/v1/swagger/repo.go
@@ -0,0 +1,92 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response Repository
+type swaggerResponseRepository struct {
+	// in:body
+	Body api.Repository `json:"body"`
+}
+
+// swagger:response RepositoryList
+type swaggerResponseRepositoryList struct {
+	// in:body
+	Body []api.Repository `json:"body"`
+}
+
+// swagger:response Branch
+type swaggerResponseBranch struct {
+	// in:body
+	Body api.Branch `json:"body"`
+}
+
+// swagger:response BranchList
+type swaggerResponseBranchList struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response Hook
+type swaggerResponseHook struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response HookList
+type swaggerResponseHookList struct {
+	// in:body
+	Body []api.Branch `json:"body"`
+}
+
+// swagger:response Release
+type swaggerResponseRelease struct {
+	// in:body
+	Body api.Release `json:"body"`
+}
+
+// swagger:response ReleaseList
+type swaggerResponseReleaseList struct {
+	// in:body
+	Body []api.Release `json:"body"`
+}
+
+// swagger:response PullRequest
+type swaggerResponsePullRequest struct {
+	// in:body
+	Body api.PullRequest `json:"body"`
+}
+
+// swagger:response PullRequestList
+type swaggerResponsePullRequestList struct {
+	// in:body
+	Body []api.PullRequest `json:"body"`
+}
+
+// swagger:response Status
+type swaggerResponseStatus struct {
+	// in:body
+	Body api.Status `json:"body"`
+}
+
+// swagger:response StatusList
+type swaggerResponseStatusList struct {
+	// in:body
+	Body []api.Status `json:"body"`
+}
+
+// swagger:response WatchInfo
+type swaggerResponseWatchInfo struct {
+	// in:body
+	Body api.WatchInfo `json:"body"`
+}
+
+// swagger:response SearchResults
+type swaggerResponseSearchResults struct {
+	Body api.SearchResults `json:"body"`
+}
diff --git a/routers/api/v1/swagger/user.go b/routers/api/v1/swagger/user.go
new file mode 100644
index 0000000000..2bb8f1b76b
--- /dev/null
+++ b/routers/api/v1/swagger/user.go
@@ -0,0 +1,33 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package swagger
+
+import (
+	api "code.gitea.io/sdk/gitea"
+)
+
+// swagger:response User
+type swaggerResponseUser struct {
+	// in:body
+	Body api.User `json:"body"`
+}
+
+// swagger:response UserList
+type swaggerResponseUserList struct {
+	// in:body
+	Body []api.User `json:"body"`
+}
+
+// swagger:response EmailList
+type swaggerResponseEmailList struct {
+	// in:body
+	Body []api.Email `json:"body"`
+}
+
+// swagger:model EditUserOption
+type swaggerModelEditUserOption struct {
+	// in:body
+	Options api.EditUserOption
+}