Updates to swagger documentation

gitea/admin_user.go

@@ -11,21 +11,17 @@ 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
+	// required: true
 	Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
-	// in: body
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	// in: body
+	// required: true
+	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	// in: body
+	// required: true
 	Password string `json:"password" binding:"Required;MaxSize(255)"`
-	// in: body
 	SendNotify bool `json:"send_notify"`
 }
 
@@ -40,31 +36,20 @@ 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
+	// required: true
+	// swagger:strfmt email
 	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,9 +20,8 @@ func (c *Client) ListForks(user, repo string) ([]*Repository, error) {
 }
 
 // CreateForkOption options for creating a fork
-// swagger:parameters createFork
 type CreateForkOption struct {
-	// in: body
+	// organization name, if forking into an organization
 	Organization *string `json:"organization"`
 }
 

gitea/hook.go

@@ -20,20 +20,20 @@ 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"`
 	URL     string            `json:"-"`
 	Config  map[string]string `json:"config"`
 	Events  []string          `json:"events"`
 	Active  bool              `json:"active"`
+	// swagger:strfmt date-time
 	Updated time.Time         `json:"updated_at"`
+	// swagger:strfmt date-time
 	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
@@ -61,15 +61,14 @@ 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
+	// required: true
+	// enum: gitea,gogs,slack,discord
 	Type string `json:"type" binding:"Required"`
-	// in: body
+	// required: true
 	Config map[string]string `json:"config" binding:"Required"`
-	// in: body
 	Events []string `json:"events"`
-	// in: body
+	// default: false
 	Active bool `json:"active"`
 }
 
@@ -94,13 +93,9 @@ 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"`
 }
 
@@ -142,25 +137,32 @@ type Payloader interface {
 	JSONPayload() ([]byte, error)
 }
 
-// PayloadUser FIXME
+// PayloadUser represents the author or committer of a commit
 type PayloadUser struct {
+	// Full name of the commit author
 	Name     string `json:"name"`
+	// swagger:strfmt email
 	Email    string `json:"email"`
 	UserName string `json:"username"`
 }
 
-// PayloadCommit FIXME: consider use same format as API when commits API are added.
+// FIXME: consider using same format as API when commits API are added.
+//        applies to PayloadCommit and PayloadCommitVerification
+
+// PayloadCommit represents a commit
 type PayloadCommit struct {
+	// sha1 hash of the commit
 	ID           string                     `json:"id"`
 	Message      string                     `json:"message"`
 	URL          string                     `json:"url"`
 	Author       *PayloadUser               `json:"author"`
 	Committer    *PayloadUser               `json:"committer"`
 	Verification *PayloadCommitVerification `json:"verification"`
+	// swagger:strfmt date-time
 	Timestamp    time.Time                  `json:"timestamp"`
 }
 
-// PayloadCommitVerification represent the GPG verification part of a commit. FIXME: like PayloadCommit consider use same format as API when commits API are added.
+// PayloadCommitVerification represents the GPG verification of a commit
 type PayloadCommitVerification struct {
 	Verified  bool   `json:"verified"`
 	Reason    string `json:"reason"`

gitea/issue.go

@@ -27,7 +27,8 @@ type PullRequestMeta struct {
 	Merged    *time.Time `json:"merged_at"`
 }
 
-// Issue an issue to a repository
+// Issue represents an issue in a repository
+// swagger:model
 type Issue struct {
 	ID        int64      `json:"id"`
 	URL       string     `json:"url"`
@@ -38,9 +39,15 @@ type Issue struct {
 	Labels    []*Label   `json:"labels"`
 	Milestone *Milestone `json:"milestone"`
 	Assignee  *User      `json:"assignee"`
+	// Whether the issue is open or closed
+	//
+	// type: string
+	// enum: open,closed
 	State     StateType  `json:"state"`
 	Comments  int        `json:"comments"`
+	// swagger:strfmt date-time
 	Created   time.Time  `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated   time.Time  `json:"updated_at"`
 
 	PullRequest *PullRequestMeta `json:"pull_request"`
@@ -78,10 +85,14 @@ func (c *Client) GetIssue(owner, repo string, index int64) (*Issue, error) {
 
 // CreateIssueOption options to create one issue
 type CreateIssueOption struct {
+	// required:true
 	Title     string  `json:"title" binding:"Required"`
 	Body      string  `json:"body"`
+	// username of assignee
 	Assignee  string  `json:"assignee"`
+	// milestone id
 	Milestone int64   `json:"milestone"`
+	// list of label ids
 	Labels    []int64 `json:"labels"`
 	Closed    bool    `json:"closed"`
 }
@@ -97,7 +108,7 @@ func (c *Client) CreateIssue(owner, repo string, opt CreateIssueOption) (*Issue,
 		jsonHeader, bytes.NewReader(body), issue)
 }
 
-// EditIssueOption edit issue options
+// EditIssueOption options for editing an issue
 type EditIssueOption struct {
 	Title     string  `json:"title"`
 	Body      *string `json:"body"`

gitea/issue_comment.go

@@ -11,15 +11,17 @@ import (
 	"time"
 )
 
-// Comment represents a comment in commit and issue page.
+// Comment represents a comment on a commit or issue
 type Comment struct {
 	ID       int64     `json:"id"`
 	HTMLURL  string    `json:"html_url"`
 	PRURL    string    `json:"pull_request_url"`
 	IssueURL string    `json:"issue_url"`
 	Poster   *User     `json:"user"`
 	Body     string    `json:"body"`
+	// swagger:strfmt date-time
 	Created  time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated  time.Time `json:"updated_at"`
 }
 
@@ -35,8 +37,9 @@ func (c *Client) ListRepoIssueComments(owner, repo string) ([]*Comment, error) {
 	return comments, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/issues/comments", owner, repo), nil, nil, &comments)
 }
 
-// CreateIssueCommentOption is option when creating an issue comment.
+// CreateIssueCommentOption options for creating a comment on an issue
 type CreateIssueCommentOption struct {
+	// required:true
 	Body string `json:"body" binding:"Required"`
 }
 
@@ -50,8 +53,9 @@ func (c *Client) CreateIssueComment(owner, repo string, index int64, opt CreateI
 	return comment, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/issues/%d/comments", owner, repo, index), jsonHeader, bytes.NewReader(body), comment)
 }
 
-// EditIssueCommentOption is option when editing an issue comment.
+// EditIssueCommentOption options for editing a comment
 type EditIssueCommentOption struct {
+	// required: true
 	Body string `json:"body" binding:"Required"`
 }
 

gitea/issue_label.go

@@ -11,14 +11,16 @@ import (
 )
 
 // Label a label to an issue or a pr
+// swagger:model
 type Label struct {
 	ID    int64  `json:"id"`
 	Name  string `json:"name"`
+	// example: 00aabb
 	Color string `json:"color"`
 	URL   string `json:"url"`
 }
 
-// ListRepoLabels list lables of one reppsitory
+// ListRepoLabels list labels of one repository
 func (c *Client) ListRepoLabels(owner, repo string) ([]*Label, error) {
 	labels := make([]*Label, 0, 10)
 	return labels, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels", owner, repo), nil, nil, &labels)
@@ -31,9 +33,12 @@ func (c *Client) GetRepoLabel(owner, repo string, id int64) (*Label, error) {
 	return label, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels/%d", owner, repo, id), nil, nil, label)
 }
 
-// CreateLabelOption create options when one label of repository
+// CreateLabelOption options for creating a label
 type CreateLabelOption struct {
+	// required:true
 	Name  string `json:"name" binding:"Required"`
+	// required:true
+	// example: #00aabb
 	Color string `json:"color" binding:"Required;Size(7)"`
 }
 
@@ -48,7 +53,7 @@ func (c *Client) CreateLabel(owner, repo string, opt CreateLabelOption) (*Label,
 		jsonHeader, bytes.NewReader(body), label)
 }
 
-// EditLabelOption edit label options
+// EditLabelOption options for editing a label
 type EditLabelOption struct {
 	Name  *string `json:"name"`
 	Color *string `json:"color"`
@@ -71,8 +76,9 @@ func (c *Client) DeleteLabel(owner, repo string, id int64) error {
 	return err
 }
 
-// IssueLabelsOption list one issue's labels options
+// IssueLabelsOption a collection of labels
 type IssueLabelsOption struct {
+	// list of label IDs
 	Labels []int64 `json:"labels"`
 }
 

gitea/issue_milestone.go

@@ -19,7 +19,9 @@ type Milestone struct {
 	State        StateType  `json:"state"`
 	OpenIssues   int        `json:"open_issues"`
 	ClosedIssues int        `json:"closed_issues"`
+	// swagger:strfmt date-time
 	Closed       *time.Time `json:"closed_at"`
+	// swagger:strfmt date-time
 	Deadline     *time.Time `json:"due_on"`
 }
 
@@ -35,10 +37,11 @@ func (c *Client) GetMilestone(owner, repo string, id int64) (*Milestone, error)
 	return milestone, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/milestones/%d", owner, repo, id), nil, nil, milestone)
 }
 
-// CreateMilestoneOption options when creating milestone
+// CreateMilestoneOption options for creating a milestone
 type CreateMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description string     `json:"description"`
+	// swagger:strfmt date-time
 	Deadline    *time.Time `json:"due_on"`
 }
 
@@ -52,7 +55,7 @@ func (c *Client) CreateMilestone(owner, repo string, opt CreateMilestoneOption)
 	return milestone, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/milestones", owner, repo), jsonHeader, bytes.NewReader(body), milestone)
 }
 
-// EditMilestoneOption options when modify milestone
+// EditMilestoneOption options for editing a milestone
 type EditMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description *string    `json:"description"`

gitea/issue_tracked_time.go

@@ -12,9 +12,9 @@ import (
 )
 
 // TrackedTime worked time for an issue / pr
-// swagger:response TrackedTime
 type TrackedTime struct {
 	ID      int64     `json:"id"`
+	// swagger:strfmt date-time
 	Created time.Time `json:"created"`
 	// Time in seconds
 	Time    int64 `json:"time"`
@@ -23,7 +23,6 @@ type TrackedTime struct {
 }
 
 // TrackedTimes represent a list of tracked times
-// swagger:response TrackedTimes
 type TrackedTimes []*TrackedTime
 
 // GetUserTrackedTimes list tracked times of a user
@@ -44,10 +43,10 @@ func (c *Client) GetMyTrackedTimes() (TrackedTimes, error) {
 	return times, c.getParsedResponse("GET", "/user/times", nil, nil, &times)
 }
 
-// AddTimeOption adds time manually to an issue
-// swagger:parameters addTime
+// AddTimeOption options for adding time to an issue
 type AddTimeOption struct {
-	// in: body
+	// time in seconds
+	// required: true
 	Time int64 `json:"time" binding:"Required"`
 }