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

1 files changed, 160 insertions, 116 deletions

diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index 34f4c5fa16..36e644373c 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -20,45 +20,40 @@ import (
 	"code.gitea.io/gitea/routers/api/v1/convert"
 )
 
-// SearchRepoOption options when searching repositories
-// swagger:parameters repoSearch
-type SearchRepoOption struct { // TODO: Move SearchRepoOption to Gitea SDK
-	// Keyword to search
-	//
-	// in: query
-	Keyword string `json:"q"`
-	// Repository owner to search
-	//
-	// in: query
-	OwnerID int64 `json:"uid"`
-	// Limit of result
-	//
-	// maximum: setting.ExplorePagingNum
-	// in: query
-	PageSize int `json:"limit"`
-	// Type of repository to search, related to owner
-	//
-	// in: query
-	SearchMode string `json:"mode"`
-	// Search only owners repositories
-	// Has effect only if owner is provided and mode is not "collaborative"
-	//
-	// in: query
-	OwnerExclusive bool `json:"exclusive"`
-}
-
 // Search repositories via options
 func Search(ctx *context.APIContext) {
-	// swagger:route GET /repos/search repository repoSearch
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: SearchResults
-	//       422: validationError
-	//       500: SearchError
-
+	// swagger:operation GET /repos/search repository repoSearch
+	// ---
+	// summary: Search for repositories
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: q
+	//   in: query
+	//   description: keyword
+	//   type: string
+	// - name: uid
+	//   in: query
+	//   description: if provided, will return only repos owned by the user with the given id
+	//   type: integer
+	// - name: limit
+	//   in: query
+	//   description: maximum number of repos to return
+	//   type: integer
+	// - name: mode
+	//   in: query
+	//   description: type of repository to search for. Supported values are
+	//                "fork", "source", "mirror" and "collaborative"
+	//   type: string
+	// - name: exclusive
+	//   in: query
+	//   description: only search for repositories owned by the authenticated user
+	//   type: boolean
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/SearchResults"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	opts := &models.SearchRepoOptions{
 		Keyword:     strings.Trim(ctx.Query("q"), " "),
 		OwnerID:     ctx.QueryInt64("uid"),
@@ -187,22 +182,23 @@ func CreateUserRepo(ctx *context.APIContext, owner *models.User, opt api.CreateR
 
 // Create one repository of mine
 func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
-	// swagger:route POST /user/repos repository user createCurrentUserRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
-	// Shouldn't reach this condition, but just in case.
+	// swagger:operation POST /user/repos repository user createCurrentUserRepo
+	// ---
+	// summary: Create a repository
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateRepoOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
 	if ctx.User.IsOrganization() {
+		// Shouldn't reach this condition, but just in case.
 		ctx.Error(422, "", "not allowed creating repository for organization")
 		return
 	}
@@ -211,20 +207,30 @@ func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
 
 // CreateOrgRepo create one repository of the organization
 func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
-	// swagger:route POST /org/{org}/repos organization createOrgRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       422: validationError
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation POST /org/{org}/repos organization createOrgRepo
+	// ---
+	// summary: Create a repository in an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: org
+	//   in: path
+	//   description: name of organization
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateRepoOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	org, err := models.GetOrgByName(ctx.Params(":org"))
 	if err != nil {
 		if models.IsErrOrgNotExist(err) {
@@ -244,19 +250,21 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
 
 // Migrate migrate remote git repository to gitea
 func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
-	// swagger:route POST /repos/migrate repository repoMigrate
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /repos/migrate repository repoMigrate
+	// ---
+	// summary: Migrate a remote git repository
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/MigrateRepoForm"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
 	ctxUser := ctx.User
 	// Not equal means context user is an organization,
 	// or is another user/organization if current user is admin.
@@ -329,29 +337,44 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
 
 // Get one repository
 func Get(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame} repository repoGet
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Repository
-	//       500: error
-
+	// swagger:operation GET /repos/{owner}/{repo} repository repoGet
+	// ---
+	// summary: Get a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Repository"
 	ctx.JSON(200, ctx.Repo.Repository.APIFormat(ctx.Repo.AccessMode))
 }
 
 // GetByID returns a single Repository
 func GetByID(ctx *context.APIContext) {
-	// swagger:route GET /repositories/{id} repository repoGetByID
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: Repository
-	//       500: error
-
+	// swagger:operation GET /repositories/{id} repository repoGetByID
+	// ---
+	// summary: Get a repository by id
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: id of the repo to get
+	//   type: integer
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Repository"
 	repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrRepoNotExist(err) {
@@ -375,16 +398,27 @@ func GetByID(ctx *context.APIContext) {
 
 // Delete one repository
 func Delete(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame} repository repoDelete
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       500: error
-
+	// swagger:operation DELETE /repos/{owner}/{repo} repository repoDelete
+	// ---
+	// summary: Delete a repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo to delete
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
 	if !ctx.Repo.IsAdmin() {
 		ctx.Error(403, "", "Must have admin rights")
 		return
@@ -408,15 +442,25 @@ func Delete(ctx *context.APIContext) {
 
 // MirrorSync adds a mirrored repository to the sync queue
 func MirrorSync(ctx *context.APIContext) {
-	// swagger:route POST /repos/{username}/{reponame}/mirror-sync repository repoMirrorSync
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: empty
-	//       403: forbidden
-
+	// swagger:operation POST /repos/{owner}/{repo}/mirror-sync repository repoMirrorSync
+	// ---
+	// summary: Sync a mirrored repository
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo to sync
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo to sync
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/empty"
 	repo := ctx.Repo.Repository
 
 	if !ctx.Repo.IsWriter() {