Skip to content
This repository was archived by the owner on Jun 8, 2019. It is now read-only.

Commit 1da52cf

Browse files
ethantkoeniglafriks
ethantkoenig
authored and
lafriks
committed
Updates to swagger documentation (#77)
1 parent 4eb2c55 commit 1da52cf

23 files changed

+140
-180
lines changed

‎gitea/admin_user.go

Lines changed: 6 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,17 @@ import (
1111
)
1212

1313
// CreateUserOption create user options
14-
// swagger:parameters adminCreateUser
1514
type CreateUserOption struct {
16-
// in: body
1715
SourceID int64 `json:"source_id"`
18-
// in: body
1916
LoginName string `json:"login_name"`
20-
// in: body
17+
// required: true
2118
Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
22-
// in: body
2319
FullName string `json:"full_name" binding:"MaxSize(100)"`
24-
// in: body
20+
// required: true
21+
// swagger:strfmt email
2522
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
26-
// in: body
23+
// required: true
2724
Password string `json:"password" binding:"Required;MaxSize(255)"`
28-
// in: body
2925
SendNotify bool `json:"send_notify"`
3026
}
3127

@@ -40,31 +36,20 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
4036
}
4137

4238
// EditUserOption edit user options
43-
// swagger:parameters adminEditUser
4439
type EditUserOption struct {
45-
// in: body
4640
SourceID int64 `json:"source_id"`
47-
// in: body
4841
LoginName string `json:"login_name"`
49-
// in: body
5042
FullName string `json:"full_name" binding:"MaxSize(100)"`
51-
// in: body
43+
// required: true
44+
// swagger:strfmt email
5245
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
53-
// in: body
5446
Password string `json:"password" binding:"MaxSize(255)"`
55-
// in: body
5647
Website string `json:"website" binding:"MaxSize(50)"`
57-
// in: body
5848
Location string `json:"location" binding:"MaxSize(50)"`
59-
// in: body
6049
Active *bool `json:"active"`
61-
// in: body
6250
Admin *bool `json:"admin"`
63-
// in: body
6451
AllowGitHook *bool `json:"allow_git_hook"`
65-
// in: body
6652
AllowImportLocal *bool `json:"allow_import_local"`
67-
// in: body
6853
MaxRepoCreation *int `json:"max_repo_creation"`
6954
}
7055

‎gitea/fork.go

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,8 @@ func (c *Client) ListForks(user, repo string) ([]*Repository, error) {
2020
}
2121

2222
// CreateForkOption options for creating a fork
23-
// swagger:parameters createFork
2423
type CreateForkOption struct {
25-
// in: body
24+
// organization name, if forking into an organization
2625
Organization *string `json:"organization"`
2726
}
2827

‎gitea/hook.go

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,20 +20,20 @@ var (
2020
)
2121

2222
// Hook a hook is a web hook when one repository changed
23-
// swagger:response Hook
2423
type Hook struct {
2524
ID int64 `json:"id"`
2625
Type string `json:"type"`
2726
URL string `json:"-"`
2827
Config map[string]string `json:"config"`
2928
Events []string `json:"events"`
3029
Active bool `json:"active"`
30+
// swagger:strfmt date-time
3131
Updated time.Time `json:"updated_at"`
32+
// swagger:strfmt date-time
3233
Created time.Time `json:"created_at"`
3334
}
3435

3536
// HookList represents a list of API hook.
36-
// swagger:response HookList
3737
type HookList []*Hook
3838

3939
// ListOrgHooks list all the hooks of one organization
@@ -61,15 +61,14 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
6161
}
6262

6363
// CreateHookOption options when create a hook
64-
// swagger:parameters orgCreateHook repoCreateHook
6564
type CreateHookOption struct {
66-
// in: body
65+
// required: true
66+
// enum: gitea,gogs,slack,discord
6767
Type string `json:"type" binding:"Required"`
68-
// in: body
68+
// required: true
6969
Config map[string]string `json:"config" binding:"Required"`
70-
// in: body
7170
Events []string `json:"events"`
72-
// in: body
71+
// default: false
7372
Active bool `json:"active"`
7473
}
7574

@@ -94,13 +93,9 @@ func (c *Client) CreateRepoHook(user, repo string, opt CreateHookOption) (*Hook,
9493
}
9594

9695
// EditHookOption options when modify one hook
97-
// swagger:parameters orgEditHook repoEditHook
9896
type EditHookOption struct {
99-
// in: body
10097
Config map[string]string `json:"config"`
101-
// in: body
10298
Events []string `json:"events"`
103-
// in: body
10499
Active *bool `json:"active"`
105100
}
106101

@@ -142,25 +137,32 @@ type Payloader interface {
142137
JSONPayload() ([]byte, error)
143138
}
144139

145-
// PayloadUser FIXME
140+
// PayloadUser represents the author or committer of a commit
146141
type PayloadUser struct {
142+
// Full name of the commit author
147143
Name string `json:"name"`
144+
// swagger:strfmt email
148145
Email string `json:"email"`
149146
UserName string `json:"username"`
150147
}
151148

152-
// PayloadCommit FIXME: consider use same format as API when commits API are added.
149+
// FIXME: consider using same format as API when commits API are added.
150+
// applies to PayloadCommit and PayloadCommitVerification
151+
152+
// PayloadCommit represents a commit
153153
type PayloadCommit struct {
154+
// sha1 hash of the commit
154155
ID string `json:"id"`
155156
Message string `json:"message"`
156157
URL string `json:"url"`
157158
Author *PayloadUser `json:"author"`
158159
Committer *PayloadUser `json:"committer"`
159160
Verification *PayloadCommitVerification `json:"verification"`
161+
// swagger:strfmt date-time
160162
Timestamp time.Time `json:"timestamp"`
161163
}
162164

163-
// PayloadCommitVerification represent the GPG verification part of a commit. FIXME: like PayloadCommit consider use same format as API when commits API are added.
165+
// PayloadCommitVerification represents the GPG verification of a commit
164166
type PayloadCommitVerification struct {
165167
Verified bool `json:"verified"`
166168
Reason string `json:"reason"`

‎gitea/issue.go

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ type PullRequestMeta struct {
2727
Merged *time.Time `json:"merged_at"`
2828
}
2929

30-
// Issue an issue to a repository
30+
// Issue represents an issue in a repository
31+
// swagger:model
3132
type Issue struct {
3233
ID int64 `json:"id"`
3334
URL string `json:"url"`
@@ -38,9 +39,15 @@ type Issue struct {
3839
Labels []*Label `json:"labels"`
3940
Milestone *Milestone `json:"milestone"`
4041
Assignee *User `json:"assignee"`
42+
// Whether the issue is open or closed
43+
//
44+
// type: string
45+
// enum: open,closed
4146
State StateType `json:"state"`
4247
Comments int `json:"comments"`
48+
// swagger:strfmt date-time
4349
Created time.Time `json:"created_at"`
50+
// swagger:strfmt date-time
4451
Updated time.Time `json:"updated_at"`
4552

4653
PullRequest *PullRequestMeta `json:"pull_request"`
@@ -78,10 +85,14 @@ func (c *Client) GetIssue(owner, repo string, index int64) (*Issue, error) {
7885

7986
// CreateIssueOption options to create one issue
8087
type CreateIssueOption struct {
88+
// required:true
8189
Title string `json:"title" binding:"Required"`
8290
Body string `json:"body"`
91+
// username of assignee
8392
Assignee string `json:"assignee"`
93+
// milestone id
8494
Milestone int64 `json:"milestone"`
95+
// list of label ids
8596
Labels []int64 `json:"labels"`
8697
Closed bool `json:"closed"`
8798
}
@@ -97,7 +108,7 @@ func (c *Client) CreateIssue(owner, repo string, opt CreateIssueOption) (*Issue,
97108
jsonHeader, bytes.NewReader(body), issue)
98109
}
99110

100-
// EditIssueOption edit issue options
111+
// EditIssueOption options for editing an issue
101112
type EditIssueOption struct {
102113
Title string `json:"title"`
103114
Body *string `json:"body"`

‎gitea/issue_comment.go

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,17 @@ import (
1111
"time"
1212
)
1313

14-
// Comment represents a comment in commit and issue page.
14+
// Comment represents a comment on a commit or issue
1515
type Comment struct {
1616
ID int64 `json:"id"`
1717
HTMLURL string `json:"html_url"`
1818
PRURL string `json:"pull_request_url"`
1919
IssueURL string `json:"issue_url"`
2020
Poster *User `json:"user"`
2121
Body string `json:"body"`
22+
// swagger:strfmt date-time
2223
Created time.Time `json:"created_at"`
24+
// swagger:strfmt date-time
2325
Updated time.Time `json:"updated_at"`
2426
}
2527

@@ -35,8 +37,9 @@ func (c *Client) ListRepoIssueComments(owner, repo string) ([]*Comment, error) {
3537
return comments, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/issues/comments", owner, repo), nil, nil, &comments)
3638
}
3739

38-
// CreateIssueCommentOption is option when creating an issue comment.
40+
// CreateIssueCommentOption options for creating a comment on an issue
3941
type CreateIssueCommentOption struct {
42+
// required:true
4043
Body string `json:"body" binding:"Required"`
4144
}
4245

@@ -50,8 +53,9 @@ func (c *Client) CreateIssueComment(owner, repo string, index int64, opt CreateI
5053
return comment, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/issues/%d/comments", owner, repo, index), jsonHeader, bytes.NewReader(body), comment)
5154
}
5255

53-
// EditIssueCommentOption is option when editing an issue comment.
56+
// EditIssueCommentOption options for editing a comment
5457
type EditIssueCommentOption struct {
58+
// required: true
5559
Body string `json:"body" binding:"Required"`
5660
}
5761

‎gitea/issue_label.go

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,16 @@ import (
1111
)
1212

1313
// Label a label to an issue or a pr
14+
// swagger:model
1415
type Label struct {
1516
ID int64 `json:"id"`
1617
Name string `json:"name"`
18+
// example: 00aabb
1719
Color string `json:"color"`
1820
URL string `json:"url"`
1921
}
2022

21-
// ListRepoLabels list lables of one reppsitory
23+
// ListRepoLabels list labels of one repository
2224
func (c *Client) ListRepoLabels(owner, repo string) ([]*Label, error) {
2325
labels := make([]*Label, 0, 10)
2426
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) {
3133
return label, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels/%d", owner, repo, id), nil, nil, label)
3234
}
3335

34-
// CreateLabelOption create options when one label of repository
36+
// CreateLabelOption options for creating a label
3537
type CreateLabelOption struct {
38+
// required:true
3639
Name string `json:"name" binding:"Required"`
40+
// required:true
41+
// example: #00aabb
3742
Color string `json:"color" binding:"Required;Size(7)"`
3843
}
3944

@@ -48,7 +53,7 @@ func (c *Client) CreateLabel(owner, repo string, opt CreateLabelOption) (*Label,
4853
jsonHeader, bytes.NewReader(body), label)
4954
}
5055

51-
// EditLabelOption edit label options
56+
// EditLabelOption options for editing a label
5257
type EditLabelOption struct {
5358
Name *string `json:"name"`
5459
Color *string `json:"color"`
@@ -71,8 +76,9 @@ func (c *Client) DeleteLabel(owner, repo string, id int64) error {
7176
return err
7277
}
7378

74-
// IssueLabelsOption list one issue's labels options
79+
// IssueLabelsOption a collection of labels
7580
type IssueLabelsOption struct {
81+
// list of label IDs
7682
Labels []int64 `json:"labels"`
7783
}
7884

‎gitea/issue_milestone.go

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ type Milestone struct {
1919
State StateType `json:"state"`
2020
OpenIssues int `json:"open_issues"`
2121
ClosedIssues int `json:"closed_issues"`
22+
// swagger:strfmt date-time
2223
Closed *time.Time `json:"closed_at"`
24+
// swagger:strfmt date-time
2325
Deadline *time.Time `json:"due_on"`
2426
}
2527

@@ -35,10 +37,11 @@ func (c *Client) GetMilestone(owner, repo string, id int64) (*Milestone, error)
3537
return milestone, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/milestones/%d", owner, repo, id), nil, nil, milestone)
3638
}
3739

38-
// CreateMilestoneOption options when creating milestone
40+
// CreateMilestoneOption options for creating a milestone
3941
type CreateMilestoneOption struct {
4042
Title string `json:"title"`
4143
Description string `json:"description"`
44+
// swagger:strfmt date-time
4245
Deadline *time.Time `json:"due_on"`
4346
}
4447

@@ -52,7 +55,7 @@ func (c *Client) CreateMilestone(owner, repo string, opt CreateMilestoneOption)
5255
return milestone, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/milestones", owner, repo), jsonHeader, bytes.NewReader(body), milestone)
5356
}
5457

55-
// EditMilestoneOption options when modify milestone
58+
// EditMilestoneOption options for editing a milestone
5659
type EditMilestoneOption struct {
5760
Title string `json:"title"`
5861
Description *string `json:"description"`

‎gitea/issue_tracked_time.go

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ import (
1212
)
1313

1414
// TrackedTime worked time for an issue / pr
15-
// swagger:response TrackedTime
1615
type TrackedTime struct {
1716
ID int64 `json:"id"`
17+
// swagger:strfmt date-time
1818
Created time.Time `json:"created"`
1919
// Time in seconds
2020
Time int64 `json:"time"`
@@ -23,7 +23,6 @@ type TrackedTime struct {
2323
}
2424

2525
// TrackedTimes represent a list of tracked times
26-
// swagger:response TrackedTimes
2726
type TrackedTimes []*TrackedTime
2827

2928
// GetUserTrackedTimes list tracked times of a user
@@ -44,10 +43,10 @@ func (c *Client) GetMyTrackedTimes() (TrackedTimes, error) {
4443
return times, c.getParsedResponse("GET", "/user/times", nil, nil, &times)
4544
}
4645

47-
// AddTimeOption adds time manually to an issue
48-
// swagger:parameters addTime
46+
// AddTimeOption options for adding time to an issue
4947
type AddTimeOption struct {
50-
// in: body
48+
// time in seconds
49+
// required: true
5150
Time int64 `json:"time" binding:"Required"`
5251
}
5352

0 commit comments

Comments
 (0)