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

vendor/code.gitea.io/sdk/gitea/admin_user.go

@@ -11,14 +11,22 @@ import (
 )
 
 // CreateUserOption create user options
+// swagger:parameters adminCreateUser
 type CreateUserOption struct {
-	SourceID   int64  `json:"source_id"`
-	LoginName  string `json:"login_name"`
-	Username   string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
-	FullName   string `json:"full_name" binding:"MaxSize(100)"`
-	Email      string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	Password   string `json:"password" binding:"MaxSize(255)"`
-	SendNotify bool   `json:"send_notify"`
+	// in: body
+	SourceID int64 `json:"source_id"`
+	// in: body
+	LoginName string `json:"login_name"`
+	// in: body
+	Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
+	// in: body
+	FullName string `json:"full_name" binding:"MaxSize(100)"`
+	// in: body
+	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
+	// in: body
+	Password string `json:"password" binding:"MaxSize(255)"`
+	// in: body
+	SendNotify bool `json:"send_notify"`
 }
 
 // AdminCreateUser create a user
@@ -32,19 +40,32 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
 }
 
 // EditUserOption edit user options
+// swagger:parameters adminEditUser
 type EditUserOption struct {
-	SourceID         int64  `json:"source_id"`
-	LoginName        string `json:"login_name"`
-	FullName         string `json:"full_name" binding:"MaxSize(100)"`
-	Email            string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	Password         string `json:"password" binding:"MaxSize(255)"`
-	Website          string `json:"website" binding:"MaxSize(50)"`
-	Location         string `json:"location" binding:"MaxSize(50)"`
-	Active           *bool  `json:"active"`
-	Admin            *bool  `json:"admin"`
-	AllowGitHook     *bool  `json:"allow_git_hook"`
-	AllowImportLocal *bool  `json:"allow_import_local"`
-	MaxRepoCreation  *int   `json:"max_repo_creation"`
+	// in: body
+	SourceID int64 `json:"source_id"`
+	// in: body
+	LoginName string `json:"login_name"`
+	// in: body
+	FullName string `json:"full_name" binding:"MaxSize(100)"`
+	// in: body
+	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
+	// in: body
+	Password string `json:"password" binding:"MaxSize(255)"`
+	// in: body
+	Website string `json:"website" binding:"MaxSize(50)"`
+	// in: body
+	Location string `json:"location" binding:"MaxSize(50)"`
+	// in: body
+	Active *bool `json:"active"`
+	// in: body
+	Admin *bool `json:"admin"`
+	// in: body
+	AllowGitHook *bool `json:"allow_git_hook"`
+	// in: body
+	AllowImportLocal *bool `json:"allow_import_local"`
+	// in: body
+	MaxRepoCreation *int `json:"max_repo_creation"`
 }
 
 // AdminEditUser modify user informations

vendor/code.gitea.io/sdk/gitea/fork.go

@@ -20,7 +20,9 @@ func (c *Client) ListForks(user, repo string) ([]*Repository, error) {
 }
 
 // CreateForkOption options for creating a fork
+// swagger:parameters createFork
 type CreateForkOption struct {
+	// in: body
 	Organization *string `json:"organization"`
 }
 

vendor/code.gitea.io/sdk/gitea/hook.go

@@ -20,6 +20,7 @@ var (
 )
 
 // Hook a hook is a web hook when one repository changed
+// swagger:response Hook
 type Hook struct {
 	ID      int64             `json:"id"`
 	Type    string            `json:"type"`
@@ -31,14 +32,18 @@ type Hook struct {
 	Created time.Time         `json:"created_at"`
 }
 
+// HookList represents a list of API hook.
+// swagger:response HookList
+type HookList []*Hook
+
 // ListOrgHooks list all the hooks of one organization
-func (c *Client) ListOrgHooks(org string) ([]*Hook, error) {
+func (c *Client) ListOrgHooks(org string) (HookList, error) {
 	hooks := make([]*Hook, 0, 10)
 	return hooks, c.getParsedResponse("GET", fmt.Sprintf("/orgs/%s/hooks", org), nil, nil, &hooks)
 }
 
 // ListRepoHooks list all the hooks of one repository
-func (c *Client) ListRepoHooks(user, repo string) ([]*Hook, error) {
+func (c *Client) ListRepoHooks(user, repo string) (HookList, error) {
 	hooks := make([]*Hook, 0, 10)
 	return hooks, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/hooks", user, repo), nil, nil, &hooks)
 }
@@ -56,11 +61,16 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
 }
 
 // CreateHookOption options when create a hook
+// swagger:parameters orgCreateHook repoCreateHook
 type CreateHookOption struct {
-	Type   string            `json:"type" binding:"Required"`
+	// in: body
+	Type string `json:"type" binding:"Required"`
+	// in: body
 	Config map[string]string `json:"config" binding:"Required"`
-	Events []string          `json:"events"`
-	Active bool              `json:"active"`
+	// in: body
+	Events []string `json:"events"`
+	// in: body
+	Active bool `json:"active"`
 }
 
 // CreateOrgHook create one hook for an organization, with options
@@ -84,10 +94,14 @@ func (c *Client) CreateRepoHook(user, repo string, opt CreateHookOption) (*Hook,
 }
 
 // EditHookOption options when modify one hook
+// swagger:parameters orgEditHook repoEditHook
 type EditHookOption struct {
+	// in: body
 	Config map[string]string `json:"config"`
-	Events []string          `json:"events"`
-	Active *bool             `json:"active"`
+	// in: body
+	Events []string `json:"events"`
+	// in: body
+	Active *bool `json:"active"`
 }
 
 // EditOrgHook modify one hook of an organization, with hook id and options

vendor/code.gitea.io/sdk/gitea/issue_tracked_time.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 gitea
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// TrackedTime worked time for an issue / pr
+// swagger:response TrackedTime
+type TrackedTime struct {
+	ID      int64     `json:"id"`
+	Created time.Time `json:"created"`
+	// Time in seconds
+	Time    int64 `json:"time"`
+	UserID  int64 `json:"user_id"`
+	IssueID int64 `json:"issue_id"`
+}
+
+// TrackedTimes represent a list of tracked times
+// swagger:response TrackedTimes
+type TrackedTimes []*TrackedTime
+
+// GetUserTrackedTimes list tracked times of a user
+func (c *Client) GetUserTrackedTimes(owner, repo, user string) (TrackedTimes, error) {
+	times := make(TrackedTimes, 0, 10)
+	return times, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/times/%s", owner, repo, user), nil, nil, &times)
+}
+
+// GetRepoTrackedTimes list tracked times of a repository
+func (c *Client) GetRepoTrackedTimes(owner, repo string) (TrackedTimes, error) {
+	times := make(TrackedTimes, 0, 10)
+	return times, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/times", owner, repo), nil, nil, &times)
+}
+
+// GetMyTrackedTimes list tracked times of the current user
+func (c *Client) GetMyTrackedTimes() (TrackedTimes, error) {
+	times := make(TrackedTimes, 0, 10)
+	return times, c.getParsedResponse("GET", "/user/times", nil, nil, &times)
+}
+
+// AddTimeOption adds time manually to an issue
+// swagger:parameters addTime
+type AddTimeOption struct {
+	// in: body
+	Time int64 `json:"time" binding:"Required"`
+}
+
+// AddTime adds time to issue with the given index
+func (c *Client) AddTime(owner, repo string, index int64, opt AddTimeOption) (*TrackedTime, error) {
+	body, err := json.Marshal(&opt)
+	if err != nil {
+		return nil, err
+	}
+	t := new(TrackedTime)
+	return t, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/issues/%d/times", owner, repo, index),
+		jsonHeader, bytes.NewReader(body), t)
+}
+
+// ListTrackedTimes get tracked times of one issue via issue id
+func (c *Client) ListTrackedTimes(owner, repo string, index int64) (TrackedTimes, error) {
+	times := make(TrackedTimes, 0, 5)
+	return times, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/issues/%d/times", owner, repo, index), nil, nil, &times)
+}

vendor/code.gitea.io/sdk/gitea/org.go

@@ -11,6 +11,7 @@ import (
 )
 
 // Organization a group of some repositories, users and teams
+// swagger:response Organization
 type Organization struct {
 	ID          int64  `json:"id"`
 	UserName    string `json:"username"`
@@ -40,12 +41,18 @@ func (c *Client) GetOrg(orgname string) (*Organization, error) {
 }
 
 // CreateOrgOption create one organization options
+// swagger:parameters adminCreateOrg
 type CreateOrgOption struct {
-	UserName    string `json:"username" binding:"Required"`
-	FullName    string `json:"full_name"`
+	// in: body
+	UserName string `json:"username" binding:"Required"`
+	// in: body
+	FullName string `json:"full_name"`
+	// in: body
 	Description string `json:"description"`
-	Website     string `json:"website"`
-	Location    string `json:"location"`
+	// in: body
+	Website string `json:"website"`
+	// in: body
+	Location string `json:"location"`
 }
 
 // EditOrgOption edit one organization options

vendor/code.gitea.io/sdk/gitea/repo.go

@@ -69,7 +69,7 @@ func (c *Client) ListOrgRepos(org string) ([]*Repository, error) {
 }
 
 // CreateRepoOption options when creating repository
-//swagger:parameters createOrgRepo
+//swagger:parameters createOrgRepo adminCreateRepo createCurrentUserRepo
 type CreateRepoOption struct {
 	// Name of the repository to create
 	//
@@ -135,15 +135,24 @@ func (c *Client) DeleteRepo(owner, repo string) error {
 }
 
 // MigrateRepoOption options when migrate repository from an external place
+// swagger:parameters repoMigrate
 type MigrateRepoOption struct {
-	CloneAddr    string `json:"clone_addr" binding:"Required"`
+	// in: body
+	CloneAddr string `json:"clone_addr" binding:"Required"`
+	// in: body
 	AuthUsername string `json:"auth_username"`
+	// in: body
 	AuthPassword string `json:"auth_password"`
-	UID          int    `json:"uid" binding:"Required"`
-	RepoName     string `json:"repo_name" binding:"Required"`
-	Mirror       bool   `json:"mirror"`
-	Private      bool   `json:"private"`
-	Description  string `json:"description"`
+	// in: body
+	UID int `json:"uid" binding:"Required"`
+	// in: body
+	RepoName string `json:"repo_name" binding:"Required"`
+	// in: body
+	Mirror bool `json:"mirror"`
+	// in: body
+	Private bool `json:"private"`
+	// in: body
+	Description string `json:"description"`
 }
 
 // MigrateRepo migrates a repository from other Git hosting sources for the

vendor/code.gitea.io/sdk/gitea/repo_key.go

@@ -34,7 +34,7 @@ func (c *Client) GetDeployKey(user, repo string, keyID int64) (*DeployKey, error
 }
 
 // CreateKeyOption options when create deploy key
-// swagger:parameters userCurrentPostKey
+// swagger:parameters userCurrentPostKey adminCreatePublicKey
 type CreateKeyOption struct {
 	// Title of the key to add
 	//

vendor/code.gitea.io/sdk/gitea/status.go

@@ -21,7 +21,7 @@ const (
 	// StatusSuccess is for when the Status is Success
 	StatusSuccess StatusState = "success"
 	// StatusError is for when the Status is Error
-	StatusError   StatusState = "error"
+	StatusError StatusState = "error"
 	// StatusFailure is for when the Status is Failure
 	StatusFailure StatusState = "failure"
 	// StatusWarning is for when the Status is Warning

vendor/code.gitea.io/sdk/gitea/user_app.go

@@ -26,7 +26,7 @@ type AccessToken struct {
 
 // AccessTokenList represents a list of API access token.
 // swagger:response AccessTokenList
-type AccessTokenList []*AccessToken 
+type AccessTokenList []*AccessToken
 
 // ListAccessTokens lista all the access tokens of user
 func (c *Client) ListAccessTokens(user, pass string) ([]*AccessToken, error) {

vendor/code.gitea.io/sdk/gitea/user_gpgkey.go

@@ -32,7 +32,7 @@ type GPGKey struct {
 	Expires           time.Time      `json:"expires_at,omitempty"`
 }
 
-// GPGKeyEmail a email attache to a GPGKey
+// GPGKeyEmail an email attached to a GPGKey
 // swagger:model GPGKeyEmail
 type GPGKeyEmail struct {
 	Email    string `json:"email"`