Merge pull request #468 from runzexia/devops-docs

devops api doc update

pkg/apis/tenant/v1alpha2/register.go

@@ -25,13 +25,20 @@ import (
 	"kubesphere.io/kubesphere/pkg/apis/tenant/v1alpha1"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/apiserver/tenant"
+	"kubesphere.io/kubesphere/pkg/models/devops"
+	"kubesphere.io/kubesphere/pkg/params"
+
 	"kubesphere.io/kubesphere/pkg/errors"
 	"kubesphere.io/kubesphere/pkg/models"
-	"kubesphere.io/kubesphere/pkg/models/devops"
+
+
 	"net/http"
 )
 
-const GroupName = "tenant.kubesphere.io"
+const (
+	GroupName = "tenant.kubesphere.io"
+	RespOK    = "ok"
+)
 
 var GroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha2"}
 
@@ -103,13 +110,27 @@ func addWebService(c *restful.Container) error {
 	ws.Route(ws.GET("/workspaces/{workspace}/devops").
 		To(tenant.ListDevopsProjects).
 		Param(ws.PathParameter("workspace", "workspace name")).
+		Param(ws.QueryParameter(params.PagingParam, "page").
+			Required(false).
+			DataFormat("limit=%d,page=%d").
+			DefaultValue("limit=10,page=1")).
+		Param(ws.QueryParameter(params.ConditionsParam, "query conditions").
+			Required(false).
+			DataFormat("key=%s,key~%s")).
 		Doc("List devops projects for the current user").
-		Returns(http.StatusOK, ok, models.PageableResponse{}).
+
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/workspaces/{workspace}/members/{username}/devops").
 		To(tenant.ListDevopsProjects).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("username", "workspace member's username")).
+		Param(ws.QueryParameter(params.PagingParam, "page").
+			Required(false).
+			DataFormat("limit=%d,page=%d").
+			DefaultValue("limit=10,page=1")).
+		Param(ws.QueryParameter(params.ConditionsParam, "query conditions").
+			Required(false).
+			DataFormat("key=%s,key~%s")).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Doc("List the devops projects for the workspace member").
 		Metadata(restfulspec.KeyOpenAPITags, tags))
@@ -117,13 +138,15 @@ func addWebService(c *restful.Container) error {
 		To(tenant.CreateDevopsProject).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Doc("Create devops project").
-		Returns(http.StatusOK, ok, devops.DevOpsProject{}).
+		Reads(devops.DevOpsProject{}).
+		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.DELETE("/workspaces/{workspace}/devops/{id}").
 		To(tenant.DeleteDevopsProject).
 		Param(ws.PathParameter("workspace", "workspace name")).
+		Param(ws.PathParameter("id", "devops project id")).
 		Doc("Delete devops project").
-		Returns(http.StatusOK, ok, errors.Error{}).
+		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/logging").
 		To(tenant.LogQuery).

pkg/gojenkins/credential.go

@@ -87,18 +87,18 @@ type CredentialResponse struct {
 	TypeName    string `json:"typeName"`
 	DisplayName string `json:"displayName"`
 	Fingerprint *struct {
-		FileName string `json:"fileName,omitempty"`
-		Hash     string `json:"hash,omitempty"`
+		FileName string `json:"file_name,omitempty" description:"credential's display name and description"`
+		Hash     string `json:"hash,omitempty" description:"credential's hash'"`
 		Usage    []*struct {
-			Name   string `json:"name,omitempty"`
+			Name   string `json:"name,omitempty" description:"jenkins pipeline full name"`
 			Ranges struct {
 				Ranges []*struct {
-					Start int `json:"start,omitempty"`
-					End   int `json:"end,omitempty"`
+					Start int `json:"start,omitempty" description:"start build number"`
+					End   int `json:"end,omitempty" description:"end build number"`
 				} `json:"ranges,omitempty"`
-			} `json:"ranges,omitempty"`
-		} `json:"usage,omitempty"`
-	} `json:"fingerprint,omitempty"`
+			} `json:"ranges,omitempty" description:"all build num using credential"`
+		} `json:"usage,omitempty" description:"all usage of credential"`
+	} `json:"fingerprint,omitempty" description:"usage of credential"`
 	Description string `json:"description,omitempty"`
 	Domain      string `json:"domain"`
 }

pkg/models/devops/common.go

@@ -79,8 +79,8 @@ const (
 )
 
 type Role struct {
-	Name        string `json:"name"`
-	Description string `json:"description"`
+	Name        string `json:"name" description:"role's name'"`
+	Description string `json:"description" description:"role 's description'"`
 }
 
 var DefaultRoles = []*Role{

pkg/models/devops/membership.go

@@ -21,11 +21,11 @@ const (
 )
 
 type DevOpsProjectMembership struct {
-	Username  string `json:"username"`
-	ProjectId string `json:"project_id" db:"project_id"`
-	Role      string `json:"role"`
-	Status    string `json:"status"`
-	GrantBy   string `json:"grand_by,omitempty"`
+	Username  string `json:"username" description:"member's username，username can uniquely identify a user"`
+	ProjectId string `json:"project_id" db:"project_id" description:"the devops projects which project membership belongs to"`
+	Role      string `json:"role" description:"devops project membership's role type. e.g. owner '"`
+	Status    string `json:"status" description:"Desperated, status of project membership"`
+	GrantBy   string `json:"grand_by,omitempty" description:"Username of the user who assigned the role"`
 }
 
 var DevOpsProjectMembershipColumns = GetColumnsFromStruct(&DevOpsProjectMembership{})

pkg/models/devops/project.go

@@ -37,15 +37,23 @@ type PageableDevOpsProject struct {
 }
 
 type DevOpsProject struct {
-	ProjectId   string    `json:"project_id" db:"project_id"`
-	Name        string    `json:"name"`
-	Description string    `json:"description,omitempty"`
-	Creator     string    `json:"creator"`
-	CreateTime  time.Time `json:"create_time"`
-	Status      string    `json:"status"`
-	Visibility  string    `json:"visibility,omitempty"`
-	Extra       string    `json:"extra,omitempty"`
-	Workspace   string    `json:"workspace"`
+	ProjectId string `json:"project_id" db:"project_id" description:"ProjectId must be unique within a namespace, it is generated by kubesphere."`
+
+	Name string `json:"name" description:"DevOps Projects's Name'"`
+
+	Description string `json:"description,omitempty" description:"DevOps Projets's Description, used to describe the DevOps Project'"`
+
+	Creator string `json:"creator" description:"Creator's username'"`
+
+	CreateTime time.Time `json:"create_time" description:"DevOps Project's Creation time'"`
+
+	Status string `json:"status" description:"DevOps project's status. e.g. active"`
+
+	Visibility string `json:"visibility,omitempty" description:"Desperated Field"`
+
+	Extra string `json:"extra,omitempty" description:"Internal Use"`
+
+	Workspace string `json:"workspace" description:"The workspace to which the devops project belongs"`
 }
 
 func NewDevOpsProject(name, description, creator, extra, workspace string) *DevOpsProject {

pkg/models/devops/project_credential.go

@@ -26,50 +26,49 @@ const (
 )
 
 type JenkinsCredential struct {
-	Id          string `json:"id"`
-	Type        string `json:"type"`
-	DisplayName string `json:"display_name,omitempty"`
+	Id          string `json:"id" description:"id of credential"`
+	Type        string `json:"type" description:"type of credential,such as ssh/kubeconfig"`
+	DisplayName string `json:"display_name,omitempty" description:"credential's display name'"`
 	Fingerprint *struct {
-		FileName string `json:"file_name,omitempty"`
-		Hash     string `json:"hash,omitempty"`
+		FileName string `json:"file_name,omitempty" description:"credential's display name and description"`
+		Hash     string `json:"hash,omitempty" description:"credential's hash'"`
 		Usage    []*struct {
-			Name   string `json:"name,omitempty"`
+			Name   string `json:"name,omitempty" description:"jenkins pipeline full name"`
 			Ranges struct {
 				Ranges []*struct {
-					Start int `json:"start,omitempty"`
-					End   int `json:"end,omitempty"`
+					Start int `json:"start,omitempty" description:"start build number"`
+					End   int `json:"end,omitempty" description:"end build number"`
 				} `json:"ranges,omitempty"`
-			} `json:"ranges,omitempty"`
-		} `json:"usage,omitempty"`
-	} `json:"fingerprint,omitempty"`
-	Description                string                      `json:"description,omitempty"`
-	Domain                     string                      `json:"domain,omitempty"`
-	CreateTime                 *time.Time                  `json:"create_time,omitempty"`
-	Creator                    string                      `json:"creator,omitempty"`
-	UsernamePasswordCredential *UsernamePasswordCredential `json:"username_password,omitempty"`
-	SshCredential              *SshCredential              `json:"ssh,omitempty"`
-	SecretTextCredential       *SecretTextCredential       `json:"secret_text,omitempty"`
-	KubeconfigCredential       *KubeconfigCredential       `json:"kubeconfig,omitempty"`
+			} `json:"ranges,omitempty" description:"all build num using credential"`
+		} `json:"usage,omitempty" description:"all usage of credential"`
+	} `json:"fingerprint,omitempty" description:"usage of credential"`
+	Description                string                      `json:"description,omitempty" description:"credential's description'"`
+	Domain                     string                      `json:"domain,omitempty" description:"credential's domain,In ks we only use the default domain, default '_''"`
+	CreateTime                 *time.Time                  `json:"create_time,omitempty" description:"credential's create_time'"`
+	Creator                    string                      `json:"creator,omitempty" description:"creator's username"`
+	UsernamePasswordCredential *UsernamePasswordCredential `json:"username_password,omitempty" description:"username password credential struct"`
+	SshCredential              *SshCredential              `json:"ssh,omitempty" description:"ssh credential struct"`
+	SecretTextCredential       *SecretTextCredential       `json:"secret_text,omitempty" description:"secret_text credential struct"`
+	KubeconfigCredential       *KubeconfigCredential       `json:"kubeconfig,omitempty" description:"kubeconfig credential struct"`
 }
 
 type UsernamePasswordCredential struct {
-	Username string `json:"username,omitempty"`
-	Password string `json:"password,omitempty"`
+	Username string `json:"username,omitempty" description:"username of username_password credential"`
+	Password string `json:"password,omitempty" description:"password of username_password credential"`
 }
 
 type SshCredential struct {
-	Username   string `json:"username,omitempty"`
-	Passphrase string `json:"passphrase,omitempty"`
-	PrivateKey string `json:"private_key,omitempty" mapstructure:"private_key"`
+	Username   string `json:"username,omitempty" description:"username of ssh credential"`
+	Passphrase string `json:"passphrase,omitempty" description:"passphrase of ssh credential, password of ssh credential"`
+	PrivateKey string `json:"private_key,omitempty" mapstructure:"private_key" description:"private key of ssh credential"`
 }
 
 type SecretTextCredential struct {
-	Secret      string `json:"secret,omitempty"`
-	Description string `json:"description,omitempty"`
+	Secret string `json:"secret,omitempty" description:"secret content of credential"`
 }
 
 type KubeconfigCredential struct {
-	Content string `json:"content,omitempty"`
+	Content string `json:"content,omitempty" description:"content of kubeconfig"`
 }
 
 const (

pkg/models/devops/project_credential_handler.go

@@ -205,7 +205,7 @@ func UpdateProjectCredential(projectId, credentialId string, credentialRequest *
 		credentialId, err := jenkinsClient.UpdateSecretTextCredentialInFolder(credentialRequest.Domain,
 			credentialId,
 			credentialRequest.SecretTextCredential.Secret,
-			credentialRequest.SecretTextCredential.Description,
+			credentialRequest.Description,
 			projectId)
 		if err != nil {
 			glog.Errorf("%+v", err)
@@ -421,17 +421,17 @@ func formatCredentialResponse(
 	response.DisplayName = jenkinsCredentialResponse.DisplayName
 	if jenkinsCredentialResponse.Fingerprint != nil && jenkinsCredentialResponse.Fingerprint.Hash != "" {
 		response.Fingerprint = &struct {
-			FileName string `json:"file_name,omitempty"`
-			Hash     string `json:"hash,omitempty"`
+			FileName string `json:"file_name,omitempty" description:"credential's display name and description"`
+			Hash     string `json:"hash,omitempty" description:"credential's hash'"`
 			Usage    []*struct {
-				Name   string `json:"name,omitempty"`
+				Name   string `json:"name,omitempty" description:"jenkins pipeline full name"`
 				Ranges struct {
 					Ranges []*struct {
-						Start int `json:"start,omitempty"`
-						End   int `json:"end,omitempty"`
+						Start int `json:"start,omitempty" description:"start build number"`
+						End   int `json:"end,omitempty" description:"end build number"`
 					} `json:"ranges,omitempty"`
-				} `json:"ranges,omitempty"`
-			} `json:"usage,omitempty"`
+				} `json:"ranges,omitempty" description:"all build num using credential"`
+			} `json:"usage,omitempty" description:"all usage of credential"`
 		}{}
 		response.Fingerprint.FileName = jenkinsCredentialResponse.Fingerprint.FileName
 		response.Fingerprint.Hash = jenkinsCredentialResponse.Fingerprint.Hash

pkg/models/devops/project_pipeline.go

@@ -53,99 +53,99 @@ type SonarStatus struct {
 }
 
 type ProjectPipeline struct {
-	Type                string               `json:"type"`
-	Pipeline            *NoScmPipeline       `json:"pipeline,omitempty"`
-	MultiBranchPipeline *MultiBranchPipeline `json:"multi_branch_pipeline,omitempty"`
+	Type                string               `json:"type" description:"type of devops pipeline, in scm or no scm"`
+	Pipeline            *NoScmPipeline       `json:"pipeline,omitempty" description:"no scm pipeline structs"`
+	MultiBranchPipeline *MultiBranchPipeline `json:"multi_branch_pipeline,omitempty" description:"in scm pipeline structs"`
 }
 
 type NoScmPipeline struct {
-	Name              string             `json:"name"`
-	Description       string             `json:"descriptio,omitempty"`
-	Discarder         *DiscarderProperty `json:"discarder,omitempty"`
-	Parameters        []*Parameter       `json:"parameters,omitempty"`
-	DisableConcurrent bool               `json:"disable_concurrent,omitempty" mapstructure:"disable_concurrent"`
-	TimerTrigger      *TimerTrigger      `json:"timer_trigger,omitempty" mapstructure:"timer_trigger"`
-	RemoteTrigger     *RemoteTrigger     `json:"remote_trigger,omitempty" mapstructure:"remote_trigger"`
-	Jenkinsfile       string             `json:"jenkinsfile,omitempty"`
+	Name              string             `json:"name" description:"name of pipeline"`
+	Description       string             `json:"descriptio,omitempty" description:"description of pipeline"`
+	Discarder         *DiscarderProperty `json:"discarder,omitempty" description:"Discarder of pipeline, managing when to drop a pipeline"`
+	Parameters        []*Parameter       `json:"parameters,omitempty" description:"Parameters define of pipeline,user could pass param when run pipeline"`
+	DisableConcurrent bool               `json:"disable_concurrent,omitempty" mapstructure:"disable_concurrent" description:"Whether to prohibit the pipeline from running in parallel"`
+	TimerTrigger      *TimerTrigger      `json:"timer_trigger,omitempty" mapstructure:"timer_trigger" description:"Timer to trigger pipeline run"`
+	RemoteTrigger     *RemoteTrigger     `json:"remote_trigger,omitempty" mapstructure:"remote_trigger" description:"Remote api define to trigger pipeline run"`
+	Jenkinsfile       string             `json:"jenkinsfile,omitempty" description:"Jenkinsfile's content'"`
 }
 
 type MultiBranchPipeline struct {
-	Name            string             `json:"name"`
-	Description     string             `json:"description,omitempty"`
-	Discarder       *DiscarderProperty `json:"discarder,omitempty"`
-	TimerTrigger    *TimerTrigger      `json:"timer_trigger,omitempty" mapstructure:"timer_trigger"`
-	SourceType      string             `json:"source_type"`
-	GitSource       *GitSource         `json:"git_source,omitempty"`
-	GitHubSource    *GithubSource      `json:"github_source,omitempty"`
-	SvnSource       *SvnSource         `json:"svn_source,omitempty"`
-	SingleSvnSource *SingleSvnSource   `json:"single_svn_source,omitempty"`
-	ScriptPath      string             `json:"script_path" mapstructure:"script_path"`
+	Name            string             `json:"name" description:"name of pipeline"`
+	Description     string             `json:"descriptio,omitempty" description:"description of pipeline"`
+	Discarder       *DiscarderProperty `json:"discarder,omitempty" description:"Discarder of pipeline, managing when to drop a pipeline"`
+	TimerTrigger    *TimerTrigger      `json:"timer_trigger,omitempty" mapstructure:"timer_trigger" description:"Timer to trigger pipeline run"`
+	SourceType      string             `json:"source_type" description:"type of scm, such as github/git/svn"`
+	GitSource       *GitSource         `json:"git_source,omitempty" description:"git scm define"`
+	GitHubSource    *GithubSource      `json:"github_source,omitempty" description:"github scm define"`
+	SvnSource       *SvnSource         `json:"svn_source,omitempty" description:"multi branch svn scm define"`
+	SingleSvnSource *SingleSvnSource   `json:"single_svn_source,omitempty" description:"single branch svn scm define"`
+	ScriptPath      string             `json:"script_path" mapstructure:"script_path" description:"script path in scm"`
 }
 
 type GitSource struct {
-	Url              string          `json:"url,omitempty" mapstructure:"url"`
-	CredentialId     string          `json:"credential_id,omitempty" mapstructure:"credential_id"`
-	DiscoverBranches bool            `json:"discover_branches,omitempty" mapstructure:"discover_branches"`
-	CloneOption      *GitCloneOption `json:"git_clone_option,omitempty" mapstructure:"git_clone_option"`
-	RegexFilter      string          `json:"regex_filter,omitempty" mapstructure:"regex_filter"`
+	Url              string          `json:"url,omitempty" mapstructure:"url" description:"url of git source"`
+	CredentialId     string          `json:"credential_id,omitempty" mapstructure:"credential_id" description:"credential id to access git source"`
+	DiscoverBranches bool            `json:"discover_branches,omitempty" mapstructure:"discover_branches" description:"Whether to discover a branch"`
+	CloneOption      *GitCloneOption `json:"git_clone_option,omitempty" mapstructure:"git_clone_option" description:"advavced git clone options"`
+	RegexFilter      string          `json:"regex_filter,omitempty" mapstructure:"regex_filter" description:"Regex used to match the name of the branch that needs to be run"`
 }
 
 type GithubSource struct {
-	Owner                string                     `json:"owner,omitempty" mapstructure:"owner"`
-	Repo                 string                     `json:"repo,omitempty" mapstructure:"repo"`
-	CredentialId         string                     `json:"credential_id,omitempty" mapstructure:"credential_id"`
-	ApiUri               string                     `json:"api_uri,omitempty" mapstructure:"api_uri"`
-	DiscoverBranches     int                        `json:"discover_branches,omitempty" mapstructure:"discover_branches"`
-	DiscoverPRFromOrigin int                        `json:"discover_pr_from_origin,omitempty" mapstructure:"discover_pr_from_origin"`
-	DiscoverPRFromForks  *GithubDiscoverPRFromForks `json:"discover_pr_from_forks,omitempty" mapstructure:"discover_pr_from_forks"`
-	CloneOption          *GitCloneOption            `json:"git_clone_option,omitempty" mapstructure:"git_clone_option"`
-	RegexFilter          string                     `json:"regex_filter,omitempty" mapstructure:"regex_filter"`
+	Owner                string                     `json:"owner,omitempty" mapstructure:"owner" description:"owner of github repo"`
+	Repo                 string                     `json:"repo,omitempty" mapstructure:"repo" description:"repo name of github repo"`
+	CredentialId         string                     `json:"credential_id,omitempty" mapstructure:"credential_id" description:"credential id to access github source"`
+	ApiUri               string                     `json:"api_uri,omitempty" mapstructure:"api_uri" description:"The api url can specify the location of the github apiserver.For private cloud configuration"`
+	DiscoverBranches     int                        `json:"discover_branches,omitempty" mapstructure:"discover_branches" description:"Discover branch configuration"`
+	DiscoverPRFromOrigin int                        `json:"discover_pr_from_origin,omitempty" mapstructure:"discover_pr_from_origin" description:"Discover origin PR configuration"`
+	DiscoverPRFromForks  *GithubDiscoverPRFromForks `json:"discover_pr_from_forks,omitempty" mapstructure:"discover_pr_from_forks" description:"Discover fork PR configuration"`
+	CloneOption          *GitCloneOption            `json:"git_clone_option,omitempty" mapstructure:"git_clone_option" description:"advavced git clone options"`
+	RegexFilter          string                     `json:"regex_filter,omitempty" mapstructure:"regex_filter" description:"Regex used to match the name of the branch that needs to be run"`
 }
 
 type GitCloneOption struct {
-	Shallow bool `json:"shallow,omitempty" mapstructure:"shallow"`
-	Timeout int  `json:"timeout,omitempty" mapstructure:"timeout"`
-	Depth   int  `json:"depth,omitempty" mapstructure:"depth"`
+	Shallow bool `json:"shallow,omitempty" mapstructure:"shallow" description:"Whether to use git shallow clone"`
+	Timeout int  `json:"timeout,omitempty" mapstructure:"timeout" description:"git clone timeout mins"`
+	Depth   int  `json:"depth,omitempty" mapstructure:"depth" description:"git clone depth"`
 }
 
 type SvnSource struct {
-	Remote       string `json:"remote,omitempty"`
-	CredentialId string `json:"credential_id,omitempty" mapstructure:"credential_id"`
-	Includes     string `json:"includes,omitempty"`
-	Excludes     string `json:"excludes,omitempty"`
+	Remote       string `json:"remote,omitempty" description:"remote address url"`
+	CredentialId string `json:"credential_id,omitempty" mapstructure:"credential_id" description:"credential id to access svn source"`
+	Includes     string `json:"includes,omitempty" description:"branches to run pipeline"`
+	Excludes     string `json:"excludes,omitempty" description:"branches do not run pipeline"`
 }
 type SingleSvnSource struct {
-	Remote       string `json:"remote,omitempty"`
-	CredentialId string `json:"credential_id,omitempty" mapstructure:"credential_id"`
+	Remote       string `json:"remote,omitempty" description:"remote address url"`
+	CredentialId string `json:"credential_id,omitempty" mapstructure:"credential_id" description:"credential id to access svn source"`
 }
 
 type GithubDiscoverPRFromForks struct {
-	Strategy int `json:"strategy,omitempty" mapstructure:"strategy"`
-	Trust    int `json:"trust,omitempty" mapstructure:"trust"`
+	Strategy int `json:"strategy,omitempty" mapstructure:"strategy" description:"github discover startegy"`
+	Trust    int `json:"trust,omitempty" mapstructure:"trust" description:"trust user type"`
 }
 
 type DiscarderProperty struct {
-	DaysToKeep string `json:"days_to_keep,omitempty" mapstructure:"days_to_keep"`
-	NumToKeep  string `json:"num_to_keep,omitempty" mapstructure:"num_to_keep"`
+	DaysToKeep string `json:"days_to_keep,omitempty" mapstructure:"days_to_keep" description:"days to keep pipeline"`
+	NumToKeep  string `json:"num_to_keep,omitempty" mapstructure:"num_to_keep" description:"nums to keep pipeline"`
 }
 
 type Parameter struct {
-	Name         string `json:"name"`
-	DefaultValue string `json:"default_value,omitempty" mapstructure:"default_value"`
-	Type         string `json:"type"`
-	Description  string `json:"description,omitempty"`
+	Name         string `json:"name" description:"name of param"`
+	DefaultValue string `json:"default_value,omitempty" mapstructure:"default_value" description:"default value of param"`
+	Type         string `json:"type" description:"type of param"`
+	Description  string `json:"description,omitempty" description:"description of pipeline"`
 }
 
 type TimerTrigger struct {
 	// user in no scm job
-	Cron string `json:"cron,omitempty"`
+	Cron string `json:"cron,omitempty" description:"jenkins cron script"`
 
 	// use in multi-branch job
-	Interval string `json:"interval,omitempty"`
+	Interval string `json:"interval,omitempty" description:"interval ms"`
 }
 
 type RemoteTrigger struct {
-	Token string `json:"token,omitempty"`
+	Token string `json:"token,omitempty" description:"remote trigger token"`
 }
 
 func replaceXmlVersion(config, oldVersion, targetVersion string) string {