Skip to content

Commit c10c420

Browse files
AlexMaryWwxiaoguang
AlexMaryW
and
wxiaoguang
authored
Add owner and parent fields clarification to docs (#35023)
Issue: #9637 Changes introduced: I have clarified the problematic terms (owner and parent) in all affected endpoints. The changes were made to relevant: - HTTP endpoint parameters' descriptions - response/request models' fields This MR is big, but most changes are the same. If you'd like me to break this MR into several smaller ones, let me know :) --------- Co-authored-by: wxiaoguang <[email protected]>
1 parent 43831ff commit c10c420

File tree

8 files changed

+62
-61
lines changed

8 files changed

+62
-61
lines changed

‎modules/structs/issue.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,8 @@ func (it IssueTemplate) Type() IssueTemplateType {
262262
// IssueMeta basic issue information
263263
// swagger:model
264264
type IssueMeta struct {
265-
Index int64 `json:"index"`
265+
Index int64 `json:"index"`
266+
// owner of the issue's repo
266267
Owner string `json:"owner"`
267268
Name string `json:"repo"`
268269
}

‎modules/structs/repo.go‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -48,15 +48,16 @@ type ExternalWiki struct {
4848

4949
// Repository represents a repository
5050
type Repository struct {
51-
ID int64 `json:"id"`
52-
Owner *User `json:"owner"`
53-
Name string `json:"name"`
54-
FullName string `json:"full_name"`
55-
Description string `json:"description"`
56-
Empty bool `json:"empty"`
57-
Private bool `json:"private"`
58-
Fork bool `json:"fork"`
59-
Template bool `json:"template"`
51+
ID int64 `json:"id"`
52+
Owner *User `json:"owner"`
53+
Name string `json:"name"`
54+
FullName string `json:"full_name"`
55+
Description string `json:"description"`
56+
Empty bool `json:"empty"`
57+
Private bool `json:"private"`
58+
Fork bool `json:"fork"`
59+
Template bool `json:"template"`
60+
// the original repository if this repository is a fork, otherwise null
6061
Parent *Repository `json:"parent,omitempty"`
6162
Mirror bool `json:"mirror"`
6263
Size int `json:"size"`
@@ -225,15 +226,13 @@ type EditRepoOption struct {
225226
EnablePrune *bool `json:"enable_prune,omitempty"`
226227
}
227228

228-
// GenerateRepoOption options when creating repository using a template
229+
// GenerateRepoOption options when creating a repository using a template
229230
// swagger:model
230231
type GenerateRepoOption struct {
231-
// The organization or person who will own the new repository
232+
// the organization's name or individual user's name who will own the new repository
232233
//
233234
// required: true
234235
Owner string `json:"owner"`
235-
// Name of the repository to create
236-
//
237236
// required: true
238237
// unique: true
239238
Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
@@ -352,9 +351,9 @@ func (gt GitServiceType) Title() string {
352351
type MigrateRepoOptions struct {
353352
// required: true
354353
CloneAddr string `json:"clone_addr" binding:"Required"`
355-
// deprecated (only for backwards compatibility)
354+
// deprecated (only for backwards compatibility, use repo_owner instead)
356355
RepoOwnerID int64 `json:"uid"`
357-
// Name of User or Organisation who will own Repo after migration
356+
// the organization's name or individual user's name who will own the migrated repository
358357
RepoOwner string `json:"repo_owner"`
359358
// required: true
360359
RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`

‎routers/api/v1/repo/action.go‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ func (Action) ListActionsSecrets(ctx *context.APIContext) {
4646
// parameters:
4747
// - name: owner
4848
// in: path
49-
// description: owner of the repository
49+
// description: owner of the repo
5050
// type: string
5151
// required: true
5252
// - name: repo
@@ -216,7 +216,7 @@ func (Action) GetVariable(ctx *context.APIContext) {
216216
// parameters:
217217
// - name: owner
218218
// in: path
219-
// description: name of the owner
219+
// description: owner of the repo
220220
// type: string
221221
// required: true
222222
// - name: repo
@@ -270,7 +270,7 @@ func (Action) DeleteVariable(ctx *context.APIContext) {
270270
// parameters:
271271
// - name: owner
272272
// in: path
273-
// description: name of the owner
273+
// description: owner of the repo
274274
// type: string
275275
// required: true
276276
// - name: repo
@@ -319,7 +319,7 @@ func (Action) CreateVariable(ctx *context.APIContext) {
319319
// parameters:
320320
// - name: owner
321321
// in: path
322-
// description: name of the owner
322+
// description: owner of the repo
323323
// type: string
324324
// required: true
325325
// - name: repo
@@ -386,7 +386,7 @@ func (Action) UpdateVariable(ctx *context.APIContext) {
386386
// parameters:
387387
// - name: owner
388388
// in: path
389-
// description: name of the owner
389+
// description: owner of the repo
390390
// type: string
391391
// required: true
392392
// - name: repo
@@ -458,7 +458,7 @@ func (Action) ListVariables(ctx *context.APIContext) {
458458
// parameters:
459459
// - name: owner
460460
// in: path
461-
// description: name of the owner
461+
// description: owner of the repo
462462
// type: string
463463
// required: true
464464
// - name: repo
@@ -660,7 +660,7 @@ func (Action) ListWorkflowJobs(ctx *context.APIContext) {
660660
// parameters:
661661
// - name: owner
662662
// in: path
663-
// description: name of the owner
663+
// description: owner of the repo
664664
// type: string
665665
// required: true
666666
// - name: repo
@@ -704,7 +704,7 @@ func (Action) ListWorkflowRuns(ctx *context.APIContext) {
704704
// parameters:
705705
// - name: owner
706706
// in: path
707-
// description: name of the owner
707+
// description: owner of the repo
708708
// type: string
709709
// required: true
710710
// - name: repo
@@ -1110,7 +1110,7 @@ func GetWorkflowRun(ctx *context.APIContext) {
11101110
// parameters:
11111111
// - name: owner
11121112
// in: path
1113-
// description: name of the owner
1113+
// description: owner of the repo
11141114
// type: string
11151115
// required: true
11161116
// - name: repo
@@ -1156,7 +1156,7 @@ func ListWorkflowRunJobs(ctx *context.APIContext) {
11561156
// parameters:
11571157
// - name: owner
11581158
// in: path
1159-
// description: name of the owner
1159+
// description: owner of the repo
11601160
// type: string
11611161
// required: true
11621162
// - name: repo
@@ -1215,7 +1215,7 @@ func GetWorkflowJob(ctx *context.APIContext) {
12151215
// parameters:
12161216
// - name: owner
12171217
// in: path
1218-
// description: name of the owner
1218+
// description: owner of the repo
12191219
// type: string
12201220
// required: true
12211221
// - name: repo
@@ -1261,7 +1261,7 @@ func GetArtifactsOfRun(ctx *context.APIContext) {
12611261
// parameters:
12621262
// - name: owner
12631263
// in: path
1264-
// description: name of the owner
1264+
// description: owner of the repo
12651265
// type: string
12661266
// required: true
12671267
// - name: repo
@@ -1330,7 +1330,7 @@ func DeleteActionRun(ctx *context.APIContext) {
13301330
// parameters:
13311331
// - name: owner
13321332
// in: path
1333-
// description: name of the owner
1333+
// description: owner of the repo
13341334
// type: string
13351335
// required: true
13361336
// - name: repo
@@ -1382,7 +1382,7 @@ func GetArtifacts(ctx *context.APIContext) {
13821382
// parameters:
13831383
// - name: owner
13841384
// in: path
1385-
// description: name of the owner
1385+
// description: owner of the repo
13861386
// type: string
13871387
// required: true
13881388
// - name: repo
@@ -1443,7 +1443,7 @@ func GetArtifact(ctx *context.APIContext) {
14431443
// parameters:
14441444
// - name: owner
14451445
// in: path
1446-
// description: name of the owner
1446+
// description: owner of the repo
14471447
// type: string
14481448
// required: true
14491449
// - name: repo
@@ -1492,7 +1492,7 @@ func DeleteArtifact(ctx *context.APIContext) {
14921492
// parameters:
14931493
// - name: owner
14941494
// in: path
1495-
// description: name of the owner
1495+
// description: owner of the repo
14961496
// type: string
14971497
// required: true
14981498
// - name: repo
@@ -1559,7 +1559,7 @@ func DownloadArtifact(ctx *context.APIContext) {
15591559
// parameters:
15601560
// - name: owner
15611561
// in: path
1562-
// description: name of the owner
1562+
// description: owner of the repo
15631563
// type: string
15641564
// required: true
15651565
// - name: repo

‎routers/api/v1/repo/actions_run.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ func DownloadActionsRunJobLogs(ctx *context.APIContext) {
2121
// parameters:
2222
// - name: owner
2323
// in: path
24-
// description: name of the owner
24+
// description: owner of the repo
2525
// type: string
2626
// required: true
2727
// - name: repo

‎routers/api/v1/repo/pull.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ func ListPullRequests(ctx *context.APIContext) {
5252
// parameters:
5353
// - name: owner
5454
// in: path
55-
// description: Owner of the repo
55+
// description: owner of the repo
5656
// type: string
5757
// required: true
5858
// - name: repo

‎routers/api/v1/repo/repo.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ func Generate(ctx *context.APIContext) {
329329
// parameters:
330330
// - name: template_owner
331331
// in: path
332-
// description: name of the template repository owner
332+
// description: owner of the template repository
333333
// type: string
334334
// required: true
335335
// - name: template_repo

‎templates/swagger/ui.tmpl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<link href="{{AssetUrlPrefix}}/css/swagger.css?v={{AssetVersion}}" rel="stylesheet">
66
</head>
77
<body>
8+
{{/* TODO: add Help & Glossary to help users understand the API, and explain some concepts like "Owner" */}}
89
<a class="swagger-back-link" href="{{AppSubUrl}}/">{{svg "octicon-reply"}}{{ctx.Locale.Tr "return_to_gitea"}}</a>
910
<div id="swagger-ui" data-source="{{AppSubUrl}}/swagger.{{.APIJSONVersion}}.json"></div>
1011
<footer class="page-footer"></footer>

0 commit comments

Comments
 (0)