Updates to swagger documentation (#77)

gitea/admin_user.go

@@ -11,21 +11,17 @@ import (
 )
 
 // CreateUserOption create user options
-// swagger:parameters adminCreateUser
 type CreateUserOption struct {
-	// in: body
 	SourceID int64 `json:"source_id"`
-	// in: body
 	LoginName string `json:"login_name"`
-	// in: body
+	// required: true
 	Username string `json:"username" binding:"Required;AlphaDashDot;MaxSize(35)"`
-	// in: body
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	// in: body
+	// required: true
+	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	// in: body
+	// required: true
 	Password string `json:"password" binding:"Required;MaxSize(255)"`
-	// in: body
 	SendNotify bool `json:"send_notify"`
 }
 
@@ -40,31 +36,20 @@ func (c *Client) AdminCreateUser(opt CreateUserOption) (*User, error) {
 }
 
 // EditUserOption edit user options
-// swagger:parameters adminEditUser
 type EditUserOption struct {
-	// in: body
 	SourceID int64 `json:"source_id"`
-	// in: body
 	LoginName string `json:"login_name"`
-	// in: body
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
-	// in: body
+	// required: true
+	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	// in: body
 	Password string `json:"password" binding:"MaxSize(255)"`
-	// in: body
 	Website string `json:"website" binding:"MaxSize(50)"`
-	// in: body
 	Location string `json:"location" binding:"MaxSize(50)"`
-	// in: body
 	Active *bool `json:"active"`
-	// in: body
 	Admin *bool `json:"admin"`
-	// in: body
 	AllowGitHook *bool `json:"allow_git_hook"`
-	// in: body
 	AllowImportLocal *bool `json:"allow_import_local"`
-	// in: body
 	MaxRepoCreation *int `json:"max_repo_creation"`
 }
 

gitea/fork.go

@@ -20,9 +20,8 @@ func (c *Client) ListForks(user, repo string) ([]*Repository, error) {
 }
 
 // CreateForkOption options for creating a fork
-// swagger:parameters createFork
 type CreateForkOption struct {
-	// in: body
+	// organization name, if forking into an organization
 	Organization *string `json:"organization"`
 }
 

gitea/hook.go

@@ -20,7 +20,6 @@ var (
 )
 
 // Hook a hook is a web hook when one repository changed
-// swagger:response Hook
 type Hook struct {
 	ID      int64             `json:"id"`
 	Type    string            `json:"type"`
@@ -28,12 +27,13 @@ type Hook struct {
 	Config  map[string]string `json:"config"`
 	Events  []string          `json:"events"`
 	Active  bool              `json:"active"`
+	// swagger:strfmt date-time
 	Updated time.Time         `json:"updated_at"`
+	// swagger:strfmt date-time
 	Created time.Time         `json:"created_at"`
 }
 
 // HookList represents a list of API hook.
-// swagger:response HookList
 type HookList []*Hook
 
 // ListOrgHooks list all the hooks of one organization
@@ -61,15 +61,14 @@ func (c *Client) GetRepoHook(user, repo string, id int64) (*Hook, error) {
 }
 
 // CreateHookOption options when create a hook
-// swagger:parameters orgCreateHook repoCreateHook
 type CreateHookOption struct {
-	// in: body
+	// required: true
+	// enum: gitea,gogs,slack,discord
 	Type string `json:"type" binding:"Required"`
-	// in: body
+	// required: true
 	Config map[string]string `json:"config" binding:"Required"`
-	// in: body
 	Events []string `json:"events"`
-	// in: body
+	// default: false
 	Active bool `json:"active"`
 }
 
@@ -94,13 +93,9 @@ func (c *Client) CreateRepoHook(user, repo string, opt CreateHookOption) (*Hook,
 }
 
 // EditHookOption options when modify one hook
-// swagger:parameters orgEditHook repoEditHook
 type EditHookOption struct {
-	// in: body
 	Config map[string]string `json:"config"`
-	// in: body
 	Events []string `json:"events"`
-	// in: body
 	Active *bool `json:"active"`
 }
 
@@ -142,25 +137,32 @@ type Payloader interface {
 	JSONPayload() ([]byte, error)
 }
 
-// PayloadUser FIXME
+// PayloadUser represents the author or committer of a commit
 type PayloadUser struct {
+	// Full name of the commit author
 	Name     string `json:"name"`
+	// swagger:strfmt email
 	Email    string `json:"email"`
 	UserName string `json:"username"`
 }
 
-// PayloadCommit FIXME: consider use same format as API when commits API are added.
+// FIXME: consider using same format as API when commits API are added.
+//        applies to PayloadCommit and PayloadCommitVerification
+
+// PayloadCommit represents a commit
 type PayloadCommit struct {
+	// sha1 hash of the commit
 	ID           string                     `json:"id"`
 	Message      string                     `json:"message"`
 	URL          string                     `json:"url"`
 	Author       *PayloadUser               `json:"author"`
 	Committer    *PayloadUser               `json:"committer"`
 	Verification *PayloadCommitVerification `json:"verification"`
+	// swagger:strfmt date-time
 	Timestamp    time.Time                  `json:"timestamp"`
 }
 
-// PayloadCommitVerification represent the GPG verification part of a commit. FIXME: like PayloadCommit consider use same format as API when commits API are added.
+// PayloadCommitVerification represents the GPG verification of a commit
 type PayloadCommitVerification struct {
 	Verified  bool   `json:"verified"`
 	Reason    string `json:"reason"`

gitea/issue.go

@@ -27,7 +27,8 @@ type PullRequestMeta struct {
 	Merged    *time.Time `json:"merged_at"`
 }
 
-// Issue an issue to a repository
+// Issue represents an issue in a repository
+// swagger:model
 type Issue struct {
 	ID        int64      `json:"id"`
 	URL       string     `json:"url"`
@@ -38,9 +39,15 @@ type Issue struct {
 	Labels    []*Label   `json:"labels"`
 	Milestone *Milestone `json:"milestone"`
 	Assignee  *User      `json:"assignee"`
+	// Whether the issue is open or closed
+	//
+	// type: string
+	// enum: open,closed
 	State     StateType  `json:"state"`
 	Comments  int        `json:"comments"`
+	// swagger:strfmt date-time
 	Created   time.Time  `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated   time.Time  `json:"updated_at"`
 
 	PullRequest *PullRequestMeta `json:"pull_request"`
@@ -78,10 +85,14 @@ func (c *Client) GetIssue(owner, repo string, index int64) (*Issue, error) {
 
 // CreateIssueOption options to create one issue
 type CreateIssueOption struct {
+	// required:true
 	Title     string  `json:"title" binding:"Required"`
 	Body      string  `json:"body"`
+	// username of assignee
 	Assignee  string  `json:"assignee"`
+	// milestone id
 	Milestone int64   `json:"milestone"`
+	// list of label ids
 	Labels    []int64 `json:"labels"`
 	Closed    bool    `json:"closed"`
 }
@@ -97,7 +108,7 @@ func (c *Client) CreateIssue(owner, repo string, opt CreateIssueOption) (*Issue,
 		jsonHeader, bytes.NewReader(body), issue)
 }
 
-// EditIssueOption edit issue options
+// EditIssueOption options for editing an issue
 type EditIssueOption struct {
 	Title     string  `json:"title"`
 	Body      *string `json:"body"`

gitea/issue_comment.go

@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-// Comment represents a comment in commit and issue page.
+// Comment represents a comment on a commit or issue
 type Comment struct {
 	ID       int64     `json:"id"`
 	HTMLURL  string    `json:"html_url"`
@@ -19,7 +19,9 @@ type Comment struct {
 	IssueURL string    `json:"issue_url"`
 	Poster   *User     `json:"user"`
 	Body     string    `json:"body"`
+	// swagger:strfmt date-time
 	Created  time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated  time.Time `json:"updated_at"`
 }
 
@@ -35,8 +37,9 @@ func (c *Client) ListRepoIssueComments(owner, repo string) ([]*Comment, error) {
 	return comments, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/issues/comments", owner, repo), nil, nil, &comments)
 }
 
-// CreateIssueCommentOption is option when creating an issue comment.
+// CreateIssueCommentOption options for creating a comment on an issue
 type CreateIssueCommentOption struct {
+	// required:true
 	Body string `json:"body" binding:"Required"`
 }
 
@@ -50,8 +53,9 @@ func (c *Client) CreateIssueComment(owner, repo string, index int64, opt CreateI
 	return comment, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/issues/%d/comments", owner, repo, index), jsonHeader, bytes.NewReader(body), comment)
 }
 
-// EditIssueCommentOption is option when editing an issue comment.
+// EditIssueCommentOption options for editing a comment
 type EditIssueCommentOption struct {
+	// required: true
 	Body string `json:"body" binding:"Required"`
 }
 

gitea/issue_label.go

@@ -11,14 +11,16 @@ import (
 )
 
 // Label a label to an issue or a pr
+// swagger:model
 type Label struct {
 	ID    int64  `json:"id"`
 	Name  string `json:"name"`
+	// example: 00aabb
 	Color string `json:"color"`
 	URL   string `json:"url"`
 }
 
-// ListRepoLabels list lables of one reppsitory
+// ListRepoLabels list labels of one repository
 func (c *Client) ListRepoLabels(owner, repo string) ([]*Label, error) {
 	labels := make([]*Label, 0, 10)
 	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) {
 	return label, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/labels/%d", owner, repo, id), nil, nil, label)
 }
 
-// CreateLabelOption create options when one label of repository
+// CreateLabelOption options for creating a label
 type CreateLabelOption struct {
+	// required:true
 	Name  string `json:"name" binding:"Required"`
+	// required:true
+	// example: #00aabb
 	Color string `json:"color" binding:"Required;Size(7)"`
 }
 
@@ -48,7 +53,7 @@ func (c *Client) CreateLabel(owner, repo string, opt CreateLabelOption) (*Label,
 		jsonHeader, bytes.NewReader(body), label)
 }
 
-// EditLabelOption edit label options
+// EditLabelOption options for editing a label
 type EditLabelOption struct {
 	Name  *string `json:"name"`
 	Color *string `json:"color"`
@@ -71,8 +76,9 @@ func (c *Client) DeleteLabel(owner, repo string, id int64) error {
 	return err
 }
 
-// IssueLabelsOption list one issue's labels options
+// IssueLabelsOption a collection of labels
 type IssueLabelsOption struct {
+	// list of label IDs
 	Labels []int64 `json:"labels"`
 }
 

gitea/issue_milestone.go

@@ -19,7 +19,9 @@ type Milestone struct {
 	State        StateType  `json:"state"`
 	OpenIssues   int        `json:"open_issues"`
 	ClosedIssues int        `json:"closed_issues"`
+	// swagger:strfmt date-time
 	Closed       *time.Time `json:"closed_at"`
+	// swagger:strfmt date-time
 	Deadline     *time.Time `json:"due_on"`
 }
 
@@ -35,10 +37,11 @@ func (c *Client) GetMilestone(owner, repo string, id int64) (*Milestone, error)
 	return milestone, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/milestones/%d", owner, repo, id), nil, nil, milestone)
 }
 
-// CreateMilestoneOption options when creating milestone
+// CreateMilestoneOption options for creating a milestone
 type CreateMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description string     `json:"description"`
+	// swagger:strfmt date-time
 	Deadline    *time.Time `json:"due_on"`
 }
 
@@ -52,7 +55,7 @@ func (c *Client) CreateMilestone(owner, repo string, opt CreateMilestoneOption)
 	return milestone, c.getParsedResponse("POST", fmt.Sprintf("/repos/%s/%s/milestones", owner, repo), jsonHeader, bytes.NewReader(body), milestone)
 }
 
-// EditMilestoneOption options when modify milestone
+// EditMilestoneOption options for editing a milestone
 type EditMilestoneOption struct {
 	Title       string     `json:"title"`
 	Description *string    `json:"description"`

gitea/issue_tracked_time.go

@@ -12,9 +12,9 @@ import (
 )
 
 // TrackedTime worked time for an issue / pr
-// swagger:response TrackedTime
 type TrackedTime struct {
 	ID      int64     `json:"id"`
+	// swagger:strfmt date-time
 	Created time.Time `json:"created"`
 	// Time in seconds
 	Time    int64 `json:"time"`
@@ -23,7 +23,6 @@ type TrackedTime struct {
 }
 
 // TrackedTimes represent a list of tracked times
-// swagger:response TrackedTimes
 type TrackedTimes []*TrackedTime
 
 // GetUserTrackedTimes list tracked times of a user
@@ -44,10 +43,10 @@ func (c *Client) GetMyTrackedTimes() (TrackedTimes, error) {
 	return times, c.getParsedResponse("GET", "/user/times", nil, nil, &times)
 }
 
-// AddTimeOption adds time manually to an issue
+// AddTimeOption options for adding time to an issue
-// swagger:parameters addTime
 type AddTimeOption struct {
-	// in: body
+	// time in seconds
+	// required: true
 	Time int64 `json:"time" binding:"Required"`
 }
 

gitea/miscellaneous.go

@@ -4,22 +4,19 @@
 
 package gitea
 
-// SearchResults results of search
+// SearchResults results of a successful search
-// swagger:response SearchResults
 type SearchResults struct {
 	OK   bool          `json:"ok"`
 	Data []*Repository `json:"data"`
 }
 
-// SearchError error of failing search
+// SearchError error of a failed search
-// swagger:response SearchError
 type SearchError struct {
 	OK    bool   `json:"ok"`
 	Error string `json:"error"`
 }
 
 // MarkdownOption markdown options
-// swagger:parameters renderMarkdown
 type MarkdownOption struct {
 	// Text markdown to render
 	//
@@ -44,13 +41,12 @@ type MarkdownOption struct {
 type MarkdownRender string
 
 // ServerVersion wraps the version of the server
-// swagger:response ServerVersion
 type ServerVersion struct {
-	Version string
+	Version string `json:"version"`
 }
 
 // ServerVersion returns the version of the server
 func (c *Client) ServerVersion() (string, error) {
 	v := ServerVersion{}
-	return v.Version, c.getParsedResponse("GET", "/version", nil, nil, &v)
+	return v.Version, c.getParsedResponse("GET", "/api/v1/version", nil, nil, &v)
 }

gitea/org.go

@@ -10,8 +10,7 @@ import (
 	"fmt"
 )
 
-// Organization a group of some repositories, users and teams
+// Organization represents an organization
-// swagger:response Organization
 type Organization struct {
 	ID          int64  `json:"id"`
 	UserName    string `json:"username"`
@@ -40,22 +39,17 @@ func (c *Client) GetOrg(orgname string) (*Organization, error) {
 	return org, c.getParsedResponse("GET", fmt.Sprintf("/orgs/%s", orgname), nil, nil, org)
 }
 
-// CreateOrgOption create one organization options
+// CreateOrgOption options for creating an organization
-// swagger:parameters adminCreateOrg
 type CreateOrgOption struct {
-	// in: body
+	// required: true
 	UserName string `json:"username" binding:"Required"`
-	// in: body
 	FullName string `json:"full_name"`
-	// in: body
 	Description string `json:"description"`
-	// in: body
 	Website string `json:"website"`
-	// in: body
 	Location string `json:"location"`
 }
 
-// EditOrgOption edit one organization options
+// EditOrgOption options for editing an organization
 type EditOrgOption struct {
 	FullName    string `json:"full_name"`
 	Description string `json:"description"`

gitea/org_team.go

@@ -4,24 +4,29 @@
 
 package gitea
 
-// Team is a sub virtual organization of one Organization
+// Team represents a team in an organization
 type Team struct {
 	ID          int64  `json:"id"`
 	Name        string `json:"name"`
 	Description string `json:"description"`
+	// enum: none,read,write,admin,owner
 	Permission  string `json:"permission"`
 }
 
-// CreateTeamOption options when create team
+// CreateTeamOption options for creating a team
 type CreateTeamOption struct {
+	// required: true
 	Name        string `json:"name" binding:"Required;AlphaDashDot;MaxSize(30)"`
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// enum: read,write,admin
 	Permission  string `json:"permission"`
 }
 
-// EditTeamOption options when edit team
+// EditTeamOption options for editing a team
 type EditTeamOption struct {
+	// required: true
 	Name        string `json:"name" binding:"Required;AlphaDashDot;MaxSize(30)"`
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// enum: read,write,admin
 	Permission  string `json:"permission"`
 }

gitea/pull.go

@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-// PullRequest represents a pull request API object.
+// PullRequest represents a pull request
 type PullRequest struct {
 	ID        int64      `json:"id"`
 	URL       string     `json:"url"`
@@ -31,6 +31,7 @@ type PullRequest struct {
 
 	Mergeable      bool       `json:"mergeable"`
 	HasMerged      bool       `json:"merged"`
+	// swagger:strfmt date-time
 	Merged         *time.Time `json:"merged_at"`
 	MergedCommitID *string    `json:"merge_commit_sha"`
 	MergedBy       *User      `json:"merged_by"`
@@ -39,11 +40,13 @@ type PullRequest struct {
 	Head      *PRBranchInfo `json:"head"`
 	MergeBase string        `json:"merge_base"`
 
+	// swagger:strfmt date-time
 	Created *time.Time `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated *time.Time `json:"updated_at"`
 }
 
-// PRBranchInfo base branch info when send a PR
+// PRBranchInfo information about a branch
 type PRBranchInfo struct {
 	Name       string      `json:"label"`
 	Ref        string      `json:"ref"`
@@ -52,7 +55,7 @@ type PRBranchInfo struct {
 	Repository *Repository `json:"repo"`
 }
 
-// ListPullRequestsOptions options when list PRs
+// ListPullRequestsOptions options for listing pull requests
 type ListPullRequestsOptions struct {
 	Page  int    `json:"page"`
 	State string `json:"state"`

gitea/release.go

@@ -13,20 +13,21 @@ import (
 
 // Release represents a repository release
 type Release struct {
-	ID           int64         `json:"id"`
+	ID           int64     `json:"id"`
-	TagName      string        `json:"tag_name"`
+	TagName      string    `json:"tag_name"`
-	Target       string        `json:"target_commitish"`
+	Target       string    `json:"target_commitish"`
-	Title        string        `json:"name"`
+	Title        string    `json:"name"`
-	Note         string        `json:"body"`
+	Note         string    `json:"body"`
-	URL          string        `json:"url"`
+	URL          string    `json:"url"`
-	TarURL       string        `json:"tarball_url"`
+	TarURL       string    `json:"tarball_url"`
-	ZipURL       string        `json:"zipball_url"`
+	ZipURL       string    `json:"zipball_url"`
-	IsDraft      bool          `json:"draft"`
+	IsDraft      bool      `json:"draft"`
-	IsPrerelease bool          `json:"prerelease"`
+	IsPrerelease bool      `json:"prerelease"`
-	CreatedAt    time.Time     `json:"created_at"`
+	// swagger:strfmt date-time
-	PublishedAt  time.Time     `json:"published_at"`
+	CreatedAt    time.Time `json:"created_at"`
-	Publisher    *User         `json:"author"`
+	// swagger:strfmt date-time
-	Attachments  []*Attachment `json:"assets"`
+	PublishedAt  time.Time `json:"published_at"`
+	Publisher    *User     `json:"author"`
 }
 
 // ListReleases list releases of a repository
@@ -47,35 +48,9 @@ func (c *Client) GetRelease(user, repo string, id int64) (*Release, error) {
 	return r, err
 }
 
-// ListReleaseAttachments gets all the assets of a release in a repository
-func (c *Client) ListReleaseAttachments(user, repo string, id int64) ([]*Attachment, error) {
-	attachments := make([]*Attachment, 0, 10)
-	err := c.getParsedResponse("GET",
-		fmt.Sprintf("/repos/%s/%s/releases/%d/assets", user, repo, id),
-		nil, nil, &attachments)
-	return attachments, err
-}
-
-// GetReleaseAttachment gets a single attachment of a release in a repository
-func (c *Client) GetReleaseAttachment(user, repo string, releaseID int64, attachmentID int64) (*Attachment, error) {
-	attachment := new(Attachment)
-	err := c.getParsedResponse("GET",
-		fmt.Sprintf("/repos/%s/%s/releases/%d/assets/%d", user, repo, releaseID, attachmentID),
-		nil, nil, &attachment)
-	return attachment, err
-}
-
-// GetLatestRelease gets the latest release in a repository. This cannot be a draft or prerelease
-func (c *Client) GetLatestRelease(user, repo string) (*Release, error) {
-	r := new(Release)
-	err := c.getParsedResponse("GET",
-		fmt.Sprintf("/repos/%s/%s/releases/latest", user, repo),
-		nil, nil, &r)
-	return r, err
-}
-
 // CreateReleaseOption options when creating a release
 type CreateReleaseOption struct {
+	// required: true
 	TagName      string `json:"tag_name" binding:"Required"`
 	Target       string `json:"target_commitish"`
 	Title        string `json:"name"`

gitea/repo.go

@@ -11,15 +11,14 @@ import (
 	"time"
 )
 
-// Permission represents a API permission.
+// Permission represents a set of permissions
 type Permission struct {
 	Admin bool `json:"admin"`
 	Push  bool `json:"push"`
 	Pull  bool `json:"pull"`
 }
 
-// Repository represents a API repository.
+// Repository represents a repository
-// swagger:response Repository
 type Repository struct {
 	ID            int64       `json:"id"`
 	Owner         *User       `json:"owner"`
@@ -41,15 +40,13 @@ type Repository struct {
 	Watchers      int         `json:"watchers_count"`
 	OpenIssues    int         `json:"open_issues_count"`
 	DefaultBranch string      `json:"default_branch"`
+	// swagger:strfmt date-time
 	Created       time.Time   `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated       time.Time   `json:"updated_at"`
 	Permissions   *Permission `json:"permissions,omitempty"`
 }
 
-// RepositoryList represents a list of API repository.
-// swagger:response RepositoryList
-type RepositoryList []*Repository
-
 // ListMyRepos lists all repositories for the authenticated user that has access to.
 func (c *Client) ListMyRepos() ([]*Repository, error) {
 	repos := make([]*Repository, 0, 10)
@@ -69,36 +66,24 @@ func (c *Client) ListOrgRepos(org string) ([]*Repository, error) {
 }
 
 // CreateRepoOption options when creating repository
-//swagger:parameters createOrgRepo adminCreateRepo createCurrentUserRepo
+// swagger:model
 type CreateRepoOption struct {
 	// Name of the repository to create
 	//
-	// in: body
+	// required: true
 	// unique: true
 	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
 	// Description of the repository to create
-	//
-	// in: body
 	Description string `json:"description" binding:"MaxSize(255)"`
-	// Is the repository to create private ?
+	// Whether the repository is private
-	//
-	// in: body
 	Private bool `json:"private"`
-	// Init the repository to create ?
+	// Whether the repository should be auto-intialized?
-	//
-	// in: body
 	AutoInit bool `json:"auto_init"`
 	// Gitignores to use
-	//
-	// in: body
 	Gitignores string `json:"gitignores"`
 	// License to use
-	//
-	// in: body
 	License string `json:"license"`
 	// Readme of the repository to create
-	//
-	// in: body
 	Readme string `json:"readme"`
 }
 
@@ -134,24 +119,18 @@ func (c *Client) DeleteRepo(owner, repo string) error {
 	return err
 }
 
-// MigrateRepoOption options when migrate repository from an external place
+// MigrateRepoOption options for migrating a repository from an external service
-// swagger:parameters repoMigrate
 type MigrateRepoOption struct {
-	// in: body
+	// required: true
 	CloneAddr string `json:"clone_addr" binding:"Required"`
-	// in: body
 	AuthUsername string `json:"auth_username"`
-	// in: body
 	AuthPassword string `json:"auth_password"`
-	// in: body
+	// required: true
 	UID int `json:"uid" binding:"Required"`
-	// in: body
+	// required: true
 	RepoName string `json:"repo_name" binding:"Required"`
-	// in: body
 	Mirror bool `json:"mirror"`
-	// in: body
 	Private bool `json:"private"`
-	// in: body
 	Description string `json:"description"`
 }
 

gitea/repo_branch.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 )
 
-// Branch represents a repository branch.
+// Branch represents a repository branch
 type Branch struct {
 	Name   string         `json:"name"`
 	Commit *PayloadCommit `json:"commit"`

gitea/repo_collaborator.go

@@ -33,7 +33,7 @@ func (c *Client) IsCollaborator(user, repo, collaborator string) (bool, error) {
 	return false, nil
 }
 
-// AddCollaboratorOption options when add some user as a collaborator of a repository
+// AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
 	Permission *string `json:"permission"`
 }

gitea/repo_key.go

@@ -17,6 +17,7 @@ type DeployKey struct {
 	Key      string    `json:"key"`
 	URL      string    `json:"url"`
 	Title    string    `json:"title"`
+	// swagger:strfmt date-time
 	Created  time.Time `json:"created_at"`
 	ReadOnly bool      `json:"read_only"`
 }
@@ -33,18 +34,15 @@ func (c *Client) GetDeployKey(user, repo string, keyID int64) (*DeployKey, error
 	return key, c.getParsedResponse("GET", fmt.Sprintf("/repos/%s/%s/keys/%d", user, repo, keyID), nil, nil, &key)
 }
 
-// CreateKeyOption options when create deploy key
+// CreateKeyOption options when creating a key
-// swagger:parameters userCurrentPostKey adminCreatePublicKey
 type CreateKeyOption struct {
 	// Title of the key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	Title string `json:"title" binding:"Required"`
 	// An armored SSH key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	Key string `json:"key" binding:"Required"`

gitea/repo_watch.go

@@ -10,8 +10,7 @@ import (
 	"time"
 )
 
-// WatchInfo represents a API watch status of one repository
+// WatchInfo represents an API watch status of one repository
-// swagger:response WatchInfo
 type WatchInfo struct {
 	Subscribed    bool        `json:"subscribed"`
 	Ignored       bool        `json:"ignored"`

gitea/status.go

@@ -37,7 +37,9 @@ type Status struct {
 	URL         string      `json:"url"`
 	Context     string      `json:"context"`
 	Creator     *User       `json:"creator"`
+	// swagger:strfmt date-time
 	Created     time.Time   `json:"created_at"`
+	// swagger:strfmt date-time
 	Updated     time.Time   `json:"updated_at"`
 }
 

gitea/user.go

@@ -9,20 +9,21 @@ import (
 	"fmt"
 )
 
-// User represents a API user.
+// User represents a user
-// swagger:response User
+// swagger:model
 type User struct {
+	// the user's id
 	ID        int64  `json:"id"`
+	// the user's username
 	UserName  string `json:"login"`
+	// the user's full name
 	FullName  string `json:"full_name"`
+	// swagger:strfmt email
 	Email     string `json:"email"`
+	// URL to the user's avatar
 	AvatarURL string `json:"avatar_url"`
 }
 
-// UserList represents a list of API user.
-// swagger:response UserList
-type UserList []*User
-
 // MarshalJSON implements the json.Marshaler interface for User, adding field(s) for backward compatibility
 func (u User) MarshalJSON() ([]byte, error) {
 	// Re-declaring User to avoid recursion

gitea/user_email.go

@@ -9,8 +9,9 @@ import (
 	"encoding/json"
 )
 
-// Email en email information of user
+// Email an email address belonging to a user
 type Email struct {
+	// swagger:strfmt email
 	Email    string `json:"email"`
 	Verified bool   `json:"verified"`
 	Primary  bool   `json:"primary"`
@@ -22,8 +23,9 @@ func (c *Client) ListEmails() ([]*Email, error) {
 	return emails, c.getParsedResponse("GET", "/user/emails", nil, nil, &emails)
 }
 
-// CreateEmailOption options when create an email
+// CreateEmailOption options when creating email addresses
 type CreateEmailOption struct {
+	// email addresses to add
 	Emails []string `json:"emails"`
 }
 
@@ -37,8 +39,14 @@ func (c *Client) AddEmail(opt CreateEmailOption) ([]*Email, error) {
 	return emails, c.getParsedResponse("POST", "/user/emails", jsonHeader, bytes.NewReader(body), emails)
 }
 
+// DeleteEmailOption options when deleting email addresses
+type DeleteEmailOption struct {
+	// email addresses to delete
+	Emails []string `json:"emails"`
+}
+
 // DeleteEmail delete one email of current users'
-func (c *Client) DeleteEmail(opt CreateEmailOption) error {
+func (c *Client) DeleteEmail(opt DeleteEmailOption) error {
 	body, err := json.Marshal(&opt)
 	if err != nil {
 		return err

gitea/user_gpgkey.go

@@ -11,12 +11,7 @@ import (
 	"time"
 )
 
-// GPGKeyList represents a list of GPGKey
-// swagger:response GPGKeyList
-type GPGKeyList []*GPGKey
-
 // GPGKey a user GPG key to sign commit and tag in repository
-// swagger:response GPGKey
 type GPGKey struct {
 	ID                int64          `json:"id"`
 	PrimaryKeyID      string         `json:"primary_key_id"`
@@ -28,7 +23,9 @@ type GPGKey struct {
 	CanEncryptComms   bool           `json:"can_encrypt_comms"`
 	CanEncryptStorage bool           `json:"can_encrypt_storage"`
 	CanCertify        bool           `json:"can_certify"`
+	// swagger:strfmt date-time
 	Created           time.Time      `json:"created_at,omitempty"`
+	// swagger:strfmt date-time
 	Expires           time.Time      `json:"expires_at,omitempty"`
 }
 
@@ -40,11 +37,9 @@ type GPGKeyEmail struct {
 }
 
 // CreateGPGKeyOption options create user GPG key
-// swagger:parameters userCurrentPostGPGKey
 type CreateGPGKeyOption struct {
 	// An armored GPG key to add
 	//
-	// in: body
 	// required: true
 	// unique: true
 	ArmoredKey string `json:"armored_public_key" binding:"Required"`

gitea/user_key.go

@@ -11,17 +11,13 @@ import (
 	"time"
 )
 
-// PublicKeyList represents a list of PublicKey
-// swagger:response PublicKeyList
-type PublicKeyList []*PublicKey
-
 // PublicKey publickey is a user key to push code to repository
-// swagger:response PublicKey
 type PublicKey struct {
 	ID      int64     `json:"id"`
 	Key     string    `json:"key"`
 	URL     string    `json:"url,omitempty"`
 	Title   string    `json:"title,omitempty"`
+	// swagger:strfmt date-time
 	Created time.Time `json:"created_at,omitempty"`
 }