Add `owner` and `parent` fields clarification to docs (#35023)

Issue: https://github.com/go-gitea/gitea/issues/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 <wxiaoguang@gmail.com>

modules/structs/issue.go

@@ -263,6 +263,7 @@ func (it IssueTemplate) Type() IssueTemplateType {
 // swagger:model
 type IssueMeta struct {
 	Index int64 `json:"index"`
+	// owner of the issue's repo
 	Owner string `json:"owner"`
 	Name  string `json:"repo"`
 }

modules/structs/repo.go

@@ -57,6 +57,7 @@ type Repository struct {
 	Private     bool   `json:"private"`
 	Fork        bool   `json:"fork"`
 	Template    bool   `json:"template"`
+	// the original repository if this repository is a fork, otherwise null
 	Parent        *Repository `json:"parent,omitempty"`
 	Mirror        bool        `json:"mirror"`
 	Size          int         `json:"size"`
@@ -225,15 +226,13 @@ type EditRepoOption struct {
 	EnablePrune *bool `json:"enable_prune,omitempty"`
 }
 
-// GenerateRepoOption options when creating repository using a template
+// GenerateRepoOption options when creating a repository using a template
 // swagger:model
 type GenerateRepoOption struct {
-	// The organization or person who will own the new repository
+	// the organization's name or individual user's name who will own the new repository
 	//
 	// required: true
 	Owner string `json:"owner"`
-	// Name of the repository to create
-	//
 	// required: true
 	// unique: true
 	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
@@ -352,9 +351,9 @@ func (gt GitServiceType) Title() string {
 type MigrateRepoOptions struct {
 	// required: true
 	CloneAddr string `json:"clone_addr" binding:"Required"`
-	// deprecated (only for backwards compatibility)
+	// deprecated (only for backwards compatibility, use repo_owner instead)
 	RepoOwnerID int64 `json:"uid"`
-	// Name of User or Organisation who will own Repo after migration
+	// the organization's name or individual user's name who will own the migrated repository
 	RepoOwner string `json:"repo_owner"`
 	// required: true
 	RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`

routers/api/v1/repo/action.go

@@ -46,7 +46,7 @@ func (Action) ListActionsSecrets(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: owner of the repository
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -216,7 +216,7 @@ func (Action) GetVariable(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -270,7 +270,7 @@ func (Action) DeleteVariable(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -319,7 +319,7 @@ func (Action) CreateVariable(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -386,7 +386,7 @@ func (Action) UpdateVariable(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -458,7 +458,7 @@ func (Action) ListVariables(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -660,7 +660,7 @@ func (Action) ListWorkflowJobs(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -704,7 +704,7 @@ func (Action) ListWorkflowRuns(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1110,7 +1110,7 @@ func GetWorkflowRun(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1156,7 +1156,7 @@ func ListWorkflowRunJobs(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1215,7 +1215,7 @@ func GetWorkflowJob(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1261,7 +1261,7 @@ func GetArtifactsOfRun(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1330,7 +1330,7 @@ func DeleteActionRun(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1382,7 +1382,7 @@ func GetArtifacts(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1443,7 +1443,7 @@ func GetArtifact(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1492,7 +1492,7 @@ func DeleteArtifact(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo
@@ -1559,7 +1559,7 @@ func DownloadArtifact(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo

routers/api/v1/repo/actions_run.go

@@ -21,7 +21,7 @@ func DownloadActionsRunJobLogs(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: name of the owner
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo

routers/api/v1/repo/pull.go

@@ -52,7 +52,7 @@ func ListPullRequests(ctx *context.APIContext) {
 	// parameters:
 	// - name: owner
 	//   in: path
-	//   description: Owner of the repo
+	//   description: owner of the repo
 	//   type: string
 	//   required: true
 	// - name: repo

routers/api/v1/repo/repo.go

@@ -329,7 +329,7 @@ func Generate(ctx *context.APIContext) {
 	// parameters:
 	// - name: template_owner
 	//   in: path
-	//   description: name of the template repository owner
+	//   description: owner of the template repository
 	//   type: string
 	//   required: true
 	// - name: template_repo

templates/swagger/ui.tmpl

@@ -5,6 +5,7 @@
 		<link href="{{AssetUrlPrefix}}/css/swagger.css?v={{AssetVersion}}" rel="stylesheet">
 	</head>
 	<body>
+		{{/* TODO: add Help & Glossary to help users understand the API, and explain some concepts like "Owner" */}}
 		<a class="swagger-back-link" href="{{AppSubUrl}}/">{{svg "octicon-reply"}}{{ctx.Locale.Tr "return_to_gitea"}}</a>
 		<div id="swagger-ui" data-source="{{AppSubUrl}}/swagger.{{.APIJSONVersion}}.json"></div>
 		<footer class="page-footer"></footer>

templates/swagger/v1_json.tmpl

@@ -4585,7 +4585,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4630,7 +4630,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4674,7 +4674,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4720,7 +4720,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4766,7 +4766,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4823,7 +4823,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -4869,7 +4869,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5108,7 +5108,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5189,7 +5189,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5233,7 +5233,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5279,7 +5279,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5331,7 +5331,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5395,7 +5395,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "owner of the repository",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5609,7 +5609,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5660,7 +5660,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5704,7 +5704,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5758,7 +5758,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -5812,7 +5812,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the owner",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -13424,7 +13424,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "Owner of the repo",
+            "description": "owner of the repo",
             "name": "owner",
             "in": "path",
             "required": true
@@ -17463,7 +17463,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "name of the template repository owner",
+            "description": "owner of the template repository",
             "name": "template_owner",
             "in": "path",
             "required": true
@@ -24968,7 +24968,7 @@
       "x-go-package": "code.gitea.io/gitea/modules/structs"
     },
     "GenerateRepoOption": {
-      "description": "GenerateRepoOption options when creating repository using a template",
+      "description": "GenerateRepoOption options when creating a repository using a template",
       "type": "object",
       "required": [
         "owner",
@@ -25006,13 +25006,12 @@
           "x-go-name": "Labels"
         },
         "name": {
-          "description": "Name of the repository to create",
           "type": "string",
           "uniqueItems": true,
           "x-go-name": "Name"
         },
         "owner": {
-          "description": "The organization or person who will own the new repository",
+          "description": "the organization's name or individual user's name who will own the new repository",
           "type": "string",
           "x-go-name": "Owner"
         },
@@ -25545,6 +25544,7 @@
           "x-go-name": "Index"
         },
         "owner": {
+          "description": "owner of the issue's repo",
           "type": "string",
           "x-go-name": "Owner"
         },
@@ -25929,7 +25929,7 @@
           "x-go-name": "RepoName"
         },
         "repo_owner": {
-          "description": "Name of User or Organisation who will own Repo after migration",
+          "description": "the organization's name or individual user's name who will own the migrated repository",
           "type": "string",
           "x-go-name": "RepoOwner"
         },
@@ -25949,7 +25949,7 @@
           "x-go-name": "Service"
         },
         "uid": {
-          "description": "deprecated (only for backwards compatibility)",
+          "description": "deprecated (only for backwards compatibility, use repo_owner instead)",
           "type": "integer",
           "format": "int64",
           "x-go-name": "RepoOwnerID"