improve

Author: wxiaoguang

modules/structs/issue.go

@@ -35,9 +35,8 @@ type PullRequestMeta struct {
 
 // RepositoryMeta basic repository information
 type RepositoryMeta struct {
-	ID   int64  `json:"id"`
-	Name string `json:"name"`
-	// owner of the repo
+	ID       int64  `json:"id"`
+	Name     string `json:"name"`
 	Owner    string `json:"owner"`
 	FullName string `json:"full_name"`
 }
@@ -264,7 +263,7 @@ func (it IssueTemplate) Type() IssueTemplateType {
 // swagger:model
 type IssueMeta struct {
 	Index int64 `json:"index"`
-	// owner of the issue
+	// owner of the issue's repo
 	Owner string `json:"owner"`
 	Name  string `json:"repo"`
 }

modules/structs/issue_stopwatch.go

@@ -10,14 +10,13 @@ import (
 // StopWatch represent a running stopwatch
 type StopWatch struct {
 	// swagger:strfmt date-time
-	Created    time.Time `json:"created"`
-	Seconds    int64     `json:"seconds"`
-	Duration   string    `json:"duration"`
-	IssueIndex int64     `json:"issue_index"`
-	IssueTitle string    `json:"issue_title"`
-	// owner of the repo
-	RepoOwnerName string `json:"repo_owner_name"`
-	RepoName      string `json:"repo_name"`
+	Created       time.Time `json:"created"`
+	Seconds       int64     `json:"seconds"`
+	Duration      string    `json:"duration"`
+	IssueIndex    int64     `json:"issue_index"`
+	IssueTitle    string    `json:"issue_title"`
+	RepoOwnerName string    `json:"repo_owner_name"`
+	RepoName      string    `json:"repo_name"`
 }
 
 // StopWatches represent a list of stopwatches

modules/structs/package.go

@@ -9,8 +9,7 @@ import (
 
 // Package represents a package
 type Package struct {
-	ID int64 `json:"id"`
-	// owner of the package
+	ID         int64       `json:"id"`
 	Owner      *User       `json:"owner"`
 	Repository *Repository `json:"repository"`
 	Creator    *User       `json:"creator"`

modules/structs/repo.go

@@ -48,8 +48,7 @@ type ExternalWiki struct {
 
 // Repository represents a repository
 type Repository struct {
-	ID int64 `json:"id"`
-	// owner of the repo
+	ID          int64  `json:"id"`
 	Owner       *User  `json:"owner"`
 	Name        string `json:"name"`
 	FullName    string `json:"full_name"`
@@ -58,7 +57,7 @@ type Repository struct {
 	Private     bool   `json:"private"`
 	Fork        bool   `json:"fork"`
 	Template    bool   `json:"template"`
-	// the original repository if the repository in the parameter is a fork; else empty
+	// the original repository if this repository is a fork, otherwise null
 	Parent        *Repository `json:"parent,omitempty"`
 	Mirror        bool        `json:"mirror"`
 	Size          int         `json:"size"`
@@ -230,7 +229,7 @@ type EditRepoOption struct {
 // GenerateRepoOption options when creating repository using a template
 // swagger:model
 type GenerateRepoOption struct {
-	// owner of the repo
+	// The organization's name or individual user's name who will own the new repository
 	//
 	// required: true
 	Owner string `json:"owner"`
@@ -293,7 +292,6 @@ type UpdateBranchRepoOption struct {
 // TransferRepoOption options when transfer a repository's ownership
 // swagger:model
 type TransferRepoOption struct {
-	// new owner of the repo
 	// required: true
 	NewOwner string `json:"new_owner"`
 	// ID of the team or teams to add to the repository. Teams can only be added to organization-owned repositories.
@@ -354,9 +352,8 @@ type MigrateRepoOptions struct {
 	// required: true
 	CloneAddr string `json:"clone_addr" binding:"Required"`
 	// deprecated (only for backwards compatibility)
-	RepoOwnerID int64 `json:"uid"`
-	// owner of the repo after migration
-	RepoOwner string `json:"repo_owner"`
+	RepoOwnerID int64  `json:"uid"`
+	RepoOwner   string `json:"repo_owner"`
 	// required: true
 	RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`
 

modules/structs/user_key.go

@@ -15,10 +15,9 @@ type PublicKey struct {
 	Title       string `json:"title,omitempty"`
 	Fingerprint string `json:"fingerprint,omitempty"`
 	// swagger:strfmt date-time
-	Created time.Time `json:"created_at"`
-	Updated time.Time `json:"last_used_at"`
-	// owner of the key
-	Owner    *User  `json:"user,omitempty"`
-	ReadOnly bool   `json:"read_only,omitempty"`
-	KeyType  string `json:"key_type,omitempty"`
+	Created  time.Time `json:"created_at"`
+	Updated  time.Time `json:"last_used_at"`
+	Owner    *User     `json:"user,omitempty"`
+	ReadOnly bool      `json:"read_only,omitempty"`
+	KeyType  string    `json:"key_type,omitempty"`
 }

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>