Improve swagger doc (#2274)

* Add swagger comment for adminCreateOrg

* Add swagger comment for admin route

* add hook swagger doc

* Add tags

* Add auth

* Fix name of responses

* Edit name method

* Update vendor

* make generate-swagger

3 files changed, 30 insertions, 17 deletions

diff --git a/routers/api/v1/repo/fork.go b/routers/api/v1/repo/fork.go
index 25464dbd78..e4f45004de 100644
--- a/routers/api/v1/repo/fork.go
+++ b/routers/api/v1/repo/fork.go
@@ -14,7 +14,7 @@ import (
 
 // ListForks list a repository's forks
 func ListForks(ctx *context.APIContext) {
-	// swagger:route GET /repos/{owner}/{repo}/forks listForks
+	// swagger:route GET /repos/{owner}/{repo}/forks repository listForks
 	//
 	//     Produces:
 	//     - application/json
@@ -42,7 +42,7 @@ func ListForks(ctx *context.APIContext) {
 
 // CreateFork create a fork of a repo
 func CreateFork(ctx *context.APIContext, form api.CreateForkOption) {
-	// swagger:route POST /repos/{owner}/{repo}/forks createFork
+	// swagger:route POST /repos/{owner}/{repo}/forks repository createFork
 	//
 	//     Produces:
 	//     - application/json
diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go
index 93dcd081d7..72dfeff3d0 100644
--- a/routers/api/v1/repo/hook.go
+++ b/routers/api/v1/repo/hook.go
@@ -15,13 +15,13 @@ import (
 
 // ListHooks list all hooks of a repository
 func ListHooks(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}/hooks
+	// swagger:route GET /repos/{username}/{reponame}/hooks repository repoListHooks
 	//
 	//     Produces:
 	//     - application/json
 	//
 	//     Responses:
-	//       200: apiHooks
+	//       200: HookList
 	//       500: error
 
 	hooks, err := models.GetWebhooksByRepoID(ctx.Repo.Repository.ID)
@@ -50,7 +50,7 @@ func GetHook(ctx *context.APIContext) {
 
 // CreateHook create a hook for a repository
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
-	// swagger:route POST /repos/{username}/{reponame}/hooks
+	// swagger:route POST /repos/{username}/{reponame}/hooks repository repoCreateHook
 	//
 	//     Consumes:
 	//     - application/json
@@ -59,7 +59,7 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 	//     - application/json
 	//
 	//     Responses:
-	//       200: apiHook
+	//       200: Hook
 	//       422: validationError
 	//       500: error
 
@@ -71,13 +71,13 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 
 // EditHook modify a hook of a repository
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
-	// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id}
+	// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id} repository repoEditHook
 	//
 	//     Produces:
 	//     - application/json
 	//
 	//     Responses:
-	//       200: apiHook //TODO
+	//       200: Hook
 	//       422: validationError
 	//       500: error
 
@@ -87,7 +87,7 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) {
 
 // DeleteHook delete a hook of a repository
 func DeleteHook(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id}
+	// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id} repository repoDeleteHook
 	//
 	//     Produces:
 	//     - application/json
diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index e44159817e..e8bf026511 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -20,7 +20,7 @@ import (
 
 // Search repositories via options
 func Search(ctx *context.APIContext) {
-	// swagger:route GET /repos/search repoSearch
+	// swagger:route GET /repos/search repository repoSearch
 	//
 	//     Produces:
 	//     - application/json
@@ -130,8 +130,21 @@ func CreateUserRepo(ctx *context.APIContext, owner *models.User, opt api.CreateR
 }
 
 // Create one repository of mine
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#create
 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.
 	if ctx.User.IsOrganization() {
 		ctx.Error(422, "", "not allowed creating repository for organization")
@@ -142,7 +155,7 @@ 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 createOrgRepo
+	// swagger:route POST /org/{org}/repos organization createOrgRepo
 	//
 	//     Consumes:
 	//     - application/json
@@ -175,7 +188,7 @@ 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
+	// swagger:route POST /repos/migrate repository repoMigrate
 	//
 	//     Consumes:
 	//     - application/json
@@ -260,7 +273,7 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
 
 // Get one repository
 func Get(ctx *context.APIContext) {
-	// swagger:route GET /repos/{username}/{reponame}
+	// swagger:route GET /repos/{username}/{reponame} repository repoGet
 	//
 	//     Produces:
 	//     - application/json
@@ -274,7 +287,7 @@ func Get(ctx *context.APIContext) {
 
 // GetByID returns a single Repository
 func GetByID(ctx *context.APIContext) {
-	// swagger:route GET /repositories/{id}
+	// swagger:route GET /repositories/{id} repository repoGetByID
 	//
 	//     Produces:
 	//     - application/json
@@ -306,7 +319,7 @@ func GetByID(ctx *context.APIContext) {
 
 // Delete one repository
 func Delete(ctx *context.APIContext) {
-	// swagger:route DELETE /repos/{username}/{reponame}
+	// swagger:route DELETE /repos/{username}/{reponame} repository repoDelete
 	//
 	//     Produces:
 	//     - application/json
@@ -339,7 +352,7 @@ 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 repoMirrorSync
+	// swagger:route POST /repos/{username}/{reponame}/mirror-sync repository repoMirrorSync
 	//
 	//     Produces:
 	//     - application/json