Generate swagger json (#1402)

- Generate swagger.json into public/
- Add swagger-ui auto-installation
- Add footer link to local swagger-ui
- Add /swagger url for using app url.
- Fix Swagger-UI version via git tag

2 files changed, 121 insertions, 22 deletions

diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go
index 2e3b655a12..93dcd081d7 100644
--- a/routers/api/v1/repo/hook.go
+++ b/routers/api/v1/repo/hook.go
@@ -14,8 +14,16 @@ import (
 )
 
 // ListHooks list all hooks of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#list-hooks
 func ListHooks(ctx *context.APIContext) {
+	// swagger:route GET /repos/{username}/{reponame}/hooks
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHooks
+	//       500: error
+
 	hooks, err := models.GetWebhooksByRepoID(ctx.Repo.Repository.ID)
 	if err != nil {
 		ctx.Error(500, "GetWebhooksByRepoID", err)
@@ -41,8 +49,20 @@ func GetHook(ctx *context.APIContext) {
 }
 
 // CreateHook create a hook for a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#create-a-hook
 func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
+	// swagger:route POST /repos/{username}/{reponame}/hooks
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHook
+	//       422: validationError
+	//       500: error
+
 	if !utils.CheckCreateHookOption(ctx, &form) {
 		return
 	}
@@ -50,14 +70,33 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) {
 }
 
 // EditHook modify a hook of a repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#edit-a-hook
 func EditHook(ctx *context.APIContext, form api.EditHookOption) {
+	// swagger:route PATCH /repos/{username}/{reponame}/hooks/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: apiHook //TODO
+	//       422: validationError
+	//       500: error
+
 	hookID := ctx.ParamsInt64(":id")
 	utils.EditRepoHook(ctx, &form, hookID)
 }
 
 // DeleteHook delete a hook of a repository
 func DeleteHook(ctx *context.APIContext) {
+	// swagger:route DELETE /repos/{username}/{reponame}/hooks/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       404: notFound
+	//       500: error
+
 	if err := models.DeleteWebhookByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")); err != nil {
 		if models.IsErrWebhookNotExist(err) {
 			ctx.Status(404)
diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go
index c0b8bb3d7b..83b1dbd26b 100644
--- a/routers/api/v1/repo/repo.go
+++ b/routers/api/v1/repo/repo.go
@@ -18,8 +18,16 @@ import (
 )
 
 // Search repositories via options
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#search-repositories
 func Search(ctx *context.APIContext) {
+	// swagger:route GET /repos/search repoSearch
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: SearchResults
+	//       500: SearchError
+
 	opts := &models.SearchRepoOptions{
 		Keyword:  strings.Trim(ctx.Query("q"), " "),
 		OwnerID:  ctx.QueryInt64("uid"),
@@ -33,9 +41,9 @@ func Search(ctx *context.APIContext) {
 		} else {
 			u, err := models.GetUserByID(opts.OwnerID)
 			if err != nil {
-				ctx.JSON(500, map[string]interface{}{
-					"ok":    false,
-					"error": err.Error(),
+				ctx.JSON(500, api.SearchError{
+					OK:    false,
+					Error: err.Error(),
 				})
 				return
 			}
@@ -48,9 +56,9 @@ func Search(ctx *context.APIContext) {
 
 	repos, count, err := models.SearchRepositoryByName(opts)
 	if err != nil {
-		ctx.JSON(500, map[string]interface{}{
-			"ok":    false,
-			"error": err.Error(),
+		ctx.JSON(500, api.SearchError{
+			OK:    false,
+			Error: err.Error(),
 		})
 		return
 	}
@@ -63,26 +71,26 @@ func Search(ctx *context.APIContext) {
 	results := make([]*api.Repository, len(repos))
 	for i, repo := range repos {
 		if err = repo.GetOwner(); err != nil {
-			ctx.JSON(500, map[string]interface{}{
-				"ok":    false,
-				"error": err.Error(),
+			ctx.JSON(500, api.SearchError{
+				OK:    false,
+				Error: err.Error(),
 			})
 			return
 		}
 		accessMode, err := models.AccessLevel(userID, repo)
 		if err != nil {
-			ctx.JSON(500, map[string]interface{}{
-				"ok":    false,
-				"error": err.Error(),
+			ctx.JSON(500, api.SearchError{
+				OK:    false,
+				Error: err.Error(),
 			})
 		}
 		results[i] = repo.APIFormat(accessMode)
 	}
 
 	ctx.SetLinkHeader(int(count), setting.API.MaxResponseItems)
-	ctx.JSON(200, map[string]interface{}{
-		"ok":   true,
-		"data": results,
+	ctx.JSON(200, api.SearchResults{
+		OK:   true,
+		Data: results,
 	})
 }
 
@@ -129,6 +137,20 @@ 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
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: Repository
+	//       422: validationError
+	//       403: forbidden
+	//       500: error
+
 	org, err := models.GetOrgByName(ctx.Params(":org"))
 	if err != nil {
 		if models.IsErrUserNotExist(err) {
@@ -147,8 +169,20 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
 }
 
 // Migrate migrate remote git repository to gitea
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#migrate
 func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
+	// swagger:route POST /repos/migrate
+	//
+	//     Consumes:
+	//     - application/json
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       201: Repository
+	//       422: validationError
+	//       500: error
+
 	ctxUser := ctx.User
 	// Not equal means context user is an organization,
 	// or is another user/organization if current user is admin.
@@ -220,8 +254,16 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
 }
 
 // Get one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#get
 func Get(ctx *context.APIContext) {
+	// swagger:route GET /repos/{username}/{reponame}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: Repository
+	//       500: error
+
 	repo := ctx.Repo.Repository
 	access, err := models.AccessLevel(ctx.User.ID, repo)
 	if err != nil {
@@ -233,6 +275,15 @@ func Get(ctx *context.APIContext) {
 
 // GetByID returns a single Repository
 func GetByID(ctx *context.APIContext) {
+	// swagger:route GET /repositories/{id}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       200: Repository
+	//       500: error
+
 	repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
 	if err != nil {
 		if models.IsErrRepoNotExist(err) {
@@ -252,8 +303,17 @@ func GetByID(ctx *context.APIContext) {
 }
 
 // Delete one repository
-// see https://github.com/gogits/go-gogs-client/wiki/Repositories#delete
 func Delete(ctx *context.APIContext) {
+	// swagger:route DELETE /repos/{username}/{reponame}
+	//
+	//     Produces:
+	//     - application/json
+	//
+	//     Responses:
+	//       204: empty
+	//       403: forbidden
+	//       500: error
+
 	if !ctx.Repo.IsAdmin() {
 		ctx.Error(403, "", "Must have admin rights")
 		return