From 1da52cf95ff3e7953227cfa0469e1c05a7d02557 Mon Sep 17 00:00:00 2001 From: Ethan Koenig Date: Sun, 12 Nov 2017 01:10:33 -0800 Subject: [PATCH] Updates to swagger documentation (#77) --- gitea/admin_user.go | 27 ++++-------------- gitea/fork.go | 3 +- gitea/hook.go | 30 ++++++++++--------- gitea/issue.go | 15 ++++++++-- gitea/issue_comment.go | 10 +++++-- gitea/issue_label.go | 14 ++++++--- gitea/issue_milestone.go | 7 +++-- gitea/issue_tracked_time.go | 9 +++--- gitea/miscellaneous.go | 12 +++----- gitea/org.go | 14 +++------ gitea/org_team.go | 11 +++++-- gitea/pull.go | 9 ++++-- gitea/release.go | 57 +++++++++++-------------------------- gitea/repo.go | 45 ++++++++--------------------- gitea/repo_branch.go | 2 +- gitea/repo_collaborator.go | 2 +- gitea/repo_key.go | 6 ++-- gitea/repo_watch.go | 3 +- gitea/status.go | 2 ++ gitea/user.go | 13 +++++---- gitea/user_email.go | 14 +++++++-- gitea/user_gpgkey.go | 9 ++---- gitea/user_key.go | 6 +--- 23 files changed, 140 insertions(+), 180 deletions(-) diff --git a/gitea/admin_user.go b/gitea/admin_user.go index 2308eea..6d736d3 100644 --- a/gitea/admin_user.go +++ b/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"` } diff --git a/gitea/fork.go b/gitea/fork.go index aa523ab..5722249 100644 --- a/gitea/fork.go +++ b/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"` } diff --git a/gitea/hook.go b/gitea/hook.go index c0beb27..b710948 100644 --- a/gitea/hook.go +++ b/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"` diff --git a/gitea/issue.go b/gitea/issue.go index 729e54f..720f54c 100644 --- a/gitea/issue.go +++ b/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"` diff --git a/gitea/issue_comment.go b/gitea/issue_comment.go index 0977f98..f146c1f 100644 --- a/gitea/issue_comment.go +++ b/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"` } diff --git a/gitea/issue_label.go b/gitea/issue_label.go index 20607f2..3acf144 100644 --- a/gitea/issue_label.go +++ b/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"` } diff --git a/gitea/issue_milestone.go b/gitea/issue_milestone.go index e35325e..d820067 100644 --- a/gitea/issue_milestone.go +++ b/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"` diff --git a/gitea/issue_tracked_time.go b/gitea/issue_tracked_time.go index 67b8a9b..dcdecbb 100644 --- a/gitea/issue_tracked_time.go +++ b/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, ×) } -// AddTimeOption adds time manually to an issue -// swagger:parameters addTime +// AddTimeOption options for adding time to an issue type AddTimeOption struct { - // in: body + // time in seconds + // required: true Time int64 `json:"time" binding:"Required"` } diff --git a/gitea/miscellaneous.go b/gitea/miscellaneous.go index 35ef115..3735047 100644 --- a/gitea/miscellaneous.go +++ b/gitea/miscellaneous.go @@ -4,22 +4,19 @@ package gitea -// SearchResults results of search -// swagger:response SearchResults +// SearchResults results of a successful search type SearchResults struct { OK bool `json:"ok"` Data []*Repository `json:"data"` } -// SearchError error of failing search -// swagger:response SearchError +// SearchError error of a failed search 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) } diff --git a/gitea/org.go b/gitea/org.go index ffdc2ff..d67d707 100644 --- a/gitea/org.go +++ b/gitea/org.go @@ -10,8 +10,7 @@ import ( "fmt" ) -// Organization a group of some repositories, users and teams -// swagger:response Organization +// Organization represents an 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 -// swagger:parameters adminCreateOrg +// CreateOrgOption options for creating an organization 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"` diff --git a/gitea/org_team.go b/gitea/org_team.go index eddaa2d..0c9a740 100644 --- a/gitea/org_team.go +++ b/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"` } diff --git a/gitea/pull.go b/gitea/pull.go index a50db96..0aa0ea8 100644 --- a/gitea/pull.go +++ b/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"` diff --git a/gitea/release.go b/gitea/release.go index 179e739..01e41e3 100644 --- a/gitea/release.go +++ b/gitea/release.go @@ -13,20 +13,21 @@ import ( // Release represents a repository release type Release struct { - ID int64 `json:"id"` - TagName string `json:"tag_name"` - Target string `json:"target_commitish"` - Title string `json:"name"` - Note string `json:"body"` - URL string `json:"url"` - TarURL string `json:"tarball_url"` - ZipURL string `json:"zipball_url"` - IsDraft bool `json:"draft"` - IsPrerelease bool `json:"prerelease"` - CreatedAt time.Time `json:"created_at"` - PublishedAt time.Time `json:"published_at"` - Publisher *User `json:"author"` - Attachments []*Attachment `json:"assets"` + ID int64 `json:"id"` + TagName string `json:"tag_name"` + Target string `json:"target_commitish"` + Title string `json:"name"` + Note string `json:"body"` + URL string `json:"url"` + TarURL string `json:"tarball_url"` + ZipURL string `json:"zipball_url"` + IsDraft bool `json:"draft"` + IsPrerelease bool `json:"prerelease"` + // swagger:strfmt date-time + CreatedAt time.Time `json:"created_at"` + // swagger:strfmt date-time + 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"` diff --git a/gitea/repo.go b/gitea/repo.go index 5b4673d..3def6e2 100644 --- a/gitea/repo.go +++ b/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. -// swagger:response Repository +// Repository represents a 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 ? - // - // in: body + // Whether the repository is private Private bool `json:"private"` - // Init the repository to create ? - // - // in: body + // Whether the repository should be auto-intialized? 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 -// swagger:parameters repoMigrate +// MigrateRepoOption options for migrating a repository from an external service 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"` } diff --git a/gitea/repo_branch.go b/gitea/repo_branch.go index fadc9e3..481fc33 100644 --- a/gitea/repo_branch.go +++ b/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"` diff --git a/gitea/repo_collaborator.go b/gitea/repo_collaborator.go index 546f247..bd61a22 100644 --- a/gitea/repo_collaborator.go +++ b/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"` } diff --git a/gitea/repo_key.go b/gitea/repo_key.go index f5f88cd..03f626c 100644 --- a/gitea/repo_key.go +++ b/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 -// swagger:parameters userCurrentPostKey adminCreatePublicKey +// CreateKeyOption options when creating a key 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"` diff --git a/gitea/repo_watch.go b/gitea/repo_watch.go index 02c5d9b..1005f9f 100644 --- a/gitea/repo_watch.go +++ b/gitea/repo_watch.go @@ -10,8 +10,7 @@ import ( "time" ) -// WatchInfo represents a API watch status of one repository -// swagger:response WatchInfo +// WatchInfo represents an API watch status of one repository type WatchInfo struct { Subscribed bool `json:"subscribed"` Ignored bool `json:"ignored"` diff --git a/gitea/status.go b/gitea/status.go index d5cdcd5..5ce2532 100644 --- a/gitea/status.go +++ b/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"` } diff --git a/gitea/user.go b/gitea/user.go index 9fe2edc..d104cc9 100644 --- a/gitea/user.go +++ b/gitea/user.go @@ -9,20 +9,21 @@ import ( "fmt" ) -// User represents a API user. -// swagger:response User +// User represents a 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 diff --git a/gitea/user_email.go b/gitea/user_email.go index e167b5d..721f521 100644 --- a/gitea/user_email.go +++ b/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 diff --git a/gitea/user_gpgkey.go b/gitea/user_gpgkey.go index 87dd749..ae5dcdc 100644 --- a/gitea/user_gpgkey.go +++ b/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"` diff --git a/gitea/user_key.go b/gitea/user_key.go index 397c6d1..419c0a5 100644 --- a/gitea/user_key.go +++ b/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"` }