Skip to content

Commit bc243ad

Browse files
sapklunny
sapk
authored and
lunny
committed
Improve swagger doc (go-gitea#67)
* Add some swagger response type * Add some swagger parameters * Add some swagger parameters * Use HookList in place of []*Hook
1 parent 82df6bc commit bc243ad

File tree

6 files changed

+91
-38
lines changed

6 files changed

+91
-38
lines changed

‎gitea/admin_user.go‎

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,22 @@ import (
1111
)
1212

1313
// CreateUserOption create user options
14+
// swagger:parameters adminCreateUser
1415
type CreateUserOption struct {
15-
SourceID int64 `json:"source_id"`
16-
LoginName string `json:"login_name"`
17-
Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
18-
FullName string `json:"full_name" binding:"MaxSize(100)"`
19-
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
20-
Password string `json:"password" binding:"MaxSize(255)"`
21-
SendNotify bool `json:"send_notify"`
16+
// in: body
17+
SourceID int64 `json:"source_id"`
18+
// in: body
19+
LoginName string `json:"login_name"`
20+
// in: body
21+
Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
22+
// in: body
23+
FullName string `json:"full_name" binding:"MaxSize(100)"`
24+
// in: body
25+
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
26+
// in: body
27+
Password string `json:"password" binding:"MaxSize(255)"`
28+
// in: body
29+
SendNotify bool `json:"send_notify"`
2230
}
2331

2432
// AdminCreateUser create a user
@@ -32,19 +40,32 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
3240
}
3341

3442
// EditUserOption edit user options
43+
// swagger:parameters adminEditUser
3544
type EditUserOption struct {
36-
SourceID int64 `json:"source_id"`
37-
LoginName string `json:"login_name"`
38-
FullName string `json:"full_name" binding:"MaxSize(100)"`
39-
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
40-
Password string `json:"password" binding:"MaxSize(255)"`
41-
Website string `json:"website" binding:"MaxSize(50)"`
42-
Location string `json:"location" binding:"MaxSize(50)"`
43-
Active *bool `json:"active"`
44-
Admin *bool `json:"admin"`
45-
AllowGitHook *bool `json:"allow_git_hook"`
46-
AllowImportLocal *bool `json:"allow_import_local"`
47-
MaxRepoCreation *int `json:"max_repo_creation"`
45+
// in: body
46+
SourceID int64 `json:"source_id"`
47+
// in: body
48+
LoginName string `json:"login_name"`
49+
// in: body
50+
FullName string `json:"full_name" binding:"MaxSize(100)"`
51+
// in: body
52+
Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
53+
// in: body
54+
Password string `json:"password" binding:"MaxSize(255)"`
55+
// in: body
56+
Website string `json:"website" binding:"MaxSize(50)"`
57+
// in: body
58+
Location string `json:"location" binding:"MaxSize(50)"`
59+
// in: body
60+
Active *bool `json:"active"`
61+
// in: body
62+
Admin *bool `json:"admin"`
63+
// in: body
64+
AllowGitHook *bool `json:"allow_git_hook"`
65+
// in: body
66+
AllowImportLocal *bool `json:"allow_import_local"`
67+
// in: body
68+
MaxRepoCreation *int `json:"max_repo_creation"`
4869
}
4970

5071
// AdminEditUser modify user informations

‎gitea/fork.go‎

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

2222
// CreateForkOption options for creating a fork
23+
// swagger:parameters createFork
2324
type CreateForkOption struct {
25+
// in: body
2426
Organization *string `json:"organization"`
2527
}
2628

‎gitea/hook.go‎

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

2222
// Hook a hook is a web hook when one repository changed
23+
// swagger:response Hook
2324
type Hook struct {
2425
ID int64 `json:"id"`
2526
Type string `json:"type"`
@@ -31,14 +32,18 @@ type Hook struct {
3132
Created time.Time `json:"created_at"`
3233
}
3334

35+
// HookList represents a list of API hook.
36+
// swagger:response HookList
37+
type HookList []*Hook
38+
3439
// ListOrgHooks list all the hooks of one organization
35-
func (c *Client) ListOrgHooks(org string) ([]*Hook, error) {
40+
func (c *Client) ListOrgHooks(org string) (HookList, error) {
3641
hooks := make([]*Hook, 0, 10)
3742
return hooks, c.getParsedResponse("GET", fmt.Sprintf("/orgs/%s/hooks", org), nil, nil, &hooks)
3843
}
3944

4045
// ListRepoHooks list all the hooks of one repository
41-
func (c *Client) ListRepoHooks(user, repo string) ([]*Hook, error) {
46+
func (c *Client) ListRepoHooks(user, repo string) (HookList, error) {
4247
hooks := make([]*Hook, 0, 10)
4348
return hooks, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/hooks", user, repo), nil, nil, &hooks)
4449
}
@@ -56,11 +61,16 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
5661
}
5762

5863
// CreateHookOption options when create a hook
64+
// swagger:parameters orgCreateHook repoCreateHook
5965
type CreateHookOption struct {
60-
Type string `json:"type" binding:"Required"`
66+
// in: body
67+
Type string `json:"type" binding:"Required"`
68+
// in: body
6169
Config map[string]string `json:"config" binding:"Required"`
62-
Events []string `json:"events"`
63-
Active bool `json:"active"`
70+
// in: body
71+
Events []string `json:"events"`
72+
// in: body
73+
Active bool `json:"active"`
6474
}
6575

6676
// CreateOrgHook create one hook for an organization, with options
@@ -84,10 +94,14 @@ func (c *Client) CreateRepoHook(user, repo string, opt CreateHookOption) (*Hook,
8494
}
8595

8696
// EditHookOption options when modify one hook
97+
// swagger:parameters orgEditHook repoEditHook
8798
type EditHookOption struct {
99+
// in: body
88100
Config map[string]string `json:"config"`
89-
Events []string `json:"events"`
90-
Active *bool `json:"active"`
101+
// in: body
102+
Events []string `json:"events"`
103+
// in: body
104+
Active *bool `json:"active"`
91105
}
92106

93107
// EditOrgHook modify one hook of an organization, with hook id and options

‎gitea/org.go‎

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

1313
// Organization a group of some repositories, users and teams
14+
// swagger:response Organization
1415
type Organization struct {
1516
ID int64 `json:"id"`
1617
UserName string `json:"username"`
@@ -40,12 +41,18 @@ func (c *Client) GetOrg(orgname string) (*Organization, error) {
4041
}
4142

4243
// CreateOrgOption create one organization options
44+
// swagger:parameters adminCreateOrg
4345
type CreateOrgOption struct {
44-
UserName string `json:"username" binding:"Required"`
45-
FullName string `json:"full_name"`
46+
// in: body
47+
UserName string `json:"username" binding:"Required"`
48+
// in: body
49+
FullName string `json:"full_name"`
50+
// in: body
4651
Description string `json:"description"`
47-
Website string `json:"website"`
48-
Location string `json:"location"`
52+
// in: body
53+
Website string `json:"website"`
54+
// in: body
55+
Location string `json:"location"`
4956
}
5057

5158
// EditOrgOption edit one organization options

‎gitea/repo.go‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ func (c *Client) ListOrgRepos(org string) ([]*Repository, error) {
6969
}
7070

7171
// CreateRepoOption options when creating repository
72-
//swagger:parameters createOrgRepo
72+
//swagger:parameters createOrgRepo adminCreateRepo createCurrentUserRepo
7373
type CreateRepoOption struct {
7474
// Name of the repository to create
7575
//
@@ -135,15 +135,24 @@ func (c *Client) DeleteRepo(owner, repo string) error {
135135
}
136136

137137
// MigrateRepoOption options when migrate repository from an external place
138+
// swagger:parameters repoMigrate
138139
type MigrateRepoOption struct {
139-
CloneAddr string `json:"clone_addr" binding:"Required"`
140+
// in: body
141+
CloneAddr string `json:"clone_addr" binding:"Required"`
142+
// in: body
140143
AuthUsername string `json:"auth_username"`
144+
// in: body
141145
AuthPassword string `json:"auth_password"`
142-
UID int `json:"uid" binding:"Required"`
143-
RepoName string `json:"repo_name" binding:"Required"`
144-
Mirror bool `json:"mirror"`
145-
Private bool `json:"private"`
146-
Description string `json:"description"`
146+
// in: body
147+
UID int `json:"uid" binding:"Required"`
148+
// in: body
149+
RepoName string `json:"repo_name" binding:"Required"`
150+
// in: body
151+
Mirror bool `json:"mirror"`
152+
// in: body
153+
Private bool `json:"private"`
154+
// in: body
155+
Description string `json:"description"`
147156
}
148157

149158
// MigrateRepo migrates a repository from other Git hosting sources for the

‎gitea/repo_key.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ func (c *Client) GetDeployKey(user, repo string, keyID int64) (*DeployKey, error
3434
}
3535

3636
// CreateKeyOption options when create deploy key
37-
// swagger:parameters userCurrentPostKey
37+
// swagger:parameters userCurrentPostKey adminCreatePublicKey
3838
type CreateKeyOption struct {
3939
// Title of the key to add
4040
//

0 commit comments

Comments
 (0)