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,13 +11,21 @@ import (
 )
 
 // CreateUserOption create user options
+// swagger:parameters adminCreateUser
 type CreateUserOption struct {
+	// 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"`
 }
 
@@ -32,18 +40,31 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
 }
 
 // EditUserOption edit user options
+// swagger:parameters adminEditUser
 type EditUserOption struct {
+	// 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"`
 }
 

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,10 +61,15 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
 }
 
 // CreateHookOption options when create a hook
+// swagger:parameters orgCreateHook repoCreateHook
 type CreateHookOption struct {
+	// in: body
 	Type string `json:"type" binding:"Required"`
+	// in: body
 	Config map[string]string `json:"config" binding:"Required"`
+	// in: body
 	Events []string `json:"events"`
+	// in: body
 	Active bool `json:"active"`
 }
 
@@ -84,9 +94,13 @@ 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"`
+	// in: body
 	Events []string `json:"events"`
+	// in: body
 	Active *bool `json:"active"`
 }
 

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,11 +41,17 @@ func (c *Client) GetOrg(orgname string) (*Organization, error) {
 }
 
 // CreateOrgOption create one organization options
+// swagger:parameters adminCreateOrg
 type CreateOrgOption struct {
+	// in: body
 	UserName string `json:"username" binding:"Required"`
+	// in: body
 	FullName string `json:"full_name"`
+	// in: body
 	Description string `json:"description"`
+	// in: body
 	Website string `json:"website"`
+	// in: body
 	Location string `json:"location"`
 }
 

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,14 +135,23 @@ func (c *Client) DeleteRepo(owner, repo string) error {
 }
 
 // MigrateRepoOption options when migrate repository from an external place
+// swagger:parameters repoMigrate
 type MigrateRepoOption struct {
+	// in: body
 	CloneAddr string `json:"clone_addr" binding:"Required"`
+	// in: body
 	AuthUsername string `json:"auth_username"`
+	// in: body
 	AuthPassword string `json:"auth_password"`
+	// 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"`
 }
 

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