Improve swagger doc (#67)

* Add some swagger response type

* Add some swagger parameters

* Add some swagger parameters

* Use HookList in place of []*Hook

gitea/admin_user.go

@@ -11,14 +11,22 @@ import (
 )
 
 // CreateUserOption create user options
+// swagger:parameters adminCreateUser
 type CreateUserOption struct {
-	SourceID   int64  `json:"source_id"`
+	// in: body
-	LoginName  string `json:"login_name"`
+	SourceID int64 `json:"source_id"`
-	Username   string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
+	// in: body
-	FullName   string `json:"full_name" binding:"MaxSize(100)"`
+	LoginName string `json:"login_name"`
-	Email      string `json:"email" binding:"Required;Email;MaxSize(254)"`
+	// in: body
-	Password   string `json:"password" binding:"MaxSize(255)"`
+	Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
-	SendNotify bool   `json:"send_notify"`
+	// 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"`
+	// in: body
-	LoginName        string `json:"login_name"`
+	SourceID int64 `json:"source_id"`
-	FullName         string `json:"full_name" binding:"MaxSize(100)"`
+	// in: body
-	Email            string `json:"email" binding:"Required;Email;MaxSize(254)"`
+	LoginName string `json:"login_name"`
-	Password         string `json:"password" binding:"MaxSize(255)"`
+	// in: body
-	Website          string `json:"website" binding:"MaxSize(50)"`
+	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	Location         string `json:"location" binding:"MaxSize(50)"`
+	// in: body
-	Active           *bool  `json:"active"`
+	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	Admin            *bool  `json:"admin"`
+	// in: body
-	AllowGitHook     *bool  `json:"allow_git_hook"`
+	Password string `json:"password" binding:"MaxSize(255)"`
-	AllowImportLocal *bool  `json:"allow_import_local"`
+	// in: body
-	MaxRepoCreation  *int   `json:"max_repo_creation"`
+	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

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"`
 }
 

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"`
+	// in: body
-	Active bool              `json:"active"`
+	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"`
+	// in: body
-	Active *bool             `json:"active"`
+	Events []string `json:"events"`
+	// in: body
+	Active *bool `json:"active"`
 }
 
 // EditOrgHook modify one hook of an organization, with hook id and options

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"`
+	// in: body
-	FullName    string `json:"full_name"`
+	UserName string `json:"username" binding:"Required"`
+	// in: body
+	FullName string `json:"full_name"`
+	// in: body
 	Description string `json:"description"`
-	Website     string `json:"website"`
+	// in: body
-	Location    string `json:"location"`
+	Website string `json:"website"`
+	// in: body
+	Location string `json:"location"`
 }
 
 // EditOrgOption edit one organization options

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"`
+	// in: body
-	RepoName     string `json:"repo_name" binding:"Required"`
+	UID int `json:"uid" binding:"Required"`
-	Mirror       bool   `json:"mirror"`
+	// in: body
-	Private      bool   `json:"private"`
+	RepoName string `json:"repo_name" binding:"Required"`
-	Description  string `json:"description"`
+	// 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

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
 	//