update docs

Signed-off-by: Nrunzexia <runzexia@yunify.com>

pkg/apis/devops/v1alpha2/register.go

@@ -50,7 +50,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}").
 		To(devopsapi.GetDevOpsProjectHandler).
-		Doc("get devops project").
+		Doc("Get devops project").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
@@ -58,15 +58,16 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.PATCH("/devops/{devops}").
 		To(devopsapi.UpdateProjectHandler).
-		Doc("update devops project").
+		Doc("Update devops project").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
+		Reads(devops.DevOpsProject{}).
 		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
 		Writes(devops.DevOpsProject{}))
 
 	webservice.Route(webservice.GET("/devops/{devops}/defaultroles").
 		To(devopsapi.GetDevOpsProjectDefaultRoles).
-		Doc("get devops project default roles").
+		Doc("Get devops project default roles").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Returns(http.StatusOK, RespOK, []devops.Role{}).
@@ -74,7 +75,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/members").
 		To(devopsapi.GetDevOpsProjectMembersHandler).
-		Doc("get devops project members").
+		Doc("Get devops project members").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.QueryParameter(params.PagingParam, "page").
@@ -89,7 +90,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/members/{members}").
 		To(devopsapi.GetDevOpsProjectMemberHandler).
-		Doc("get devops project member").
+		Doc("Get devops project member").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("members", "member's username")).
@@ -98,7 +99,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.POST("/devops/{devops}/members").
 		To(devopsapi.AddDevOpsProjectMemberHandler).
-		Doc("add devops project members").
+		Doc("Add devops project members").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Returns(http.StatusOK, RespOK, devops.DevOpsProjectMembership{}).
@@ -106,7 +107,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.PATCH("/devops/{devops}/members/{members}").
 		To(devopsapi.UpdateDevOpsProjectMemberHandler).
-		Doc("update devops project members").
+		Doc("Update devops project members").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("members", "member's username")).
@@ -115,7 +116,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.DELETE("/devops/{devops}/members/{members}").
 		To(devopsapi.DeleteDevOpsProjectMemberHandler).
-		Doc("delete devops project members").
+		Doc("Delete devops project members").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("members", "member's username")).
@@ -123,7 +124,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.POST("/devops/{devops}/pipelines").
 		To(devopsapi.CreateDevOpsProjectPipelineHandler).
-		Doc("add devops project pipeline").
+		Doc("Add devops project pipeline").
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Returns(http.StatusOK, RespOK, devops.ProjectPipeline{}).
@@ -132,7 +133,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.PUT("/devops/{devops}/pipelines/{pipelines}").
 		To(devopsapi.UpdateDevOpsProjectPipelineHandler).
-		Doc("update devops project pipeline").
+		Doc("Update devops project pipeline").
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("pipelines", "pipeline name")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
@@ -142,7 +143,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/pipelines/{pipelines}/config").
 		To(devopsapi.GetDevOpsProjectPipelineHandler).
-		Doc("get devops project pipeline config").
+		Doc("Get devops project pipeline config").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("pipelines", "pipeline name")).
@@ -151,7 +152,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/pipelines/{pipelines}/sonarStatus").
 		To(devopsapi.GetPipelineSonarStatusHandler).
-		Doc("get devops project pipeline sonarStatus").
+		Doc("Get devops project pipeline sonarStatus").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("pipelines", "pipeline name")).
@@ -160,7 +161,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/pipelines/{pipelines}/branches/{branches}/sonarStatus").
 		To(devopsapi.GetMultiBranchesPipelineSonarStatusHandler).
-		Doc("get devops project pipeline sonarStatus").
+		Doc("Get devops project pipeline sonarStatus").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("pipelines", "pipeline name")).
@@ -170,21 +171,21 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.DELETE("/devops/{devops}/pipelines/{pipelines}").
 		To(devopsapi.DeleteDevOpsProjectPipelineHandler).
-		Doc("delete devops project pipeline").
+		Doc("Delete devops project pipeline").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("pipelines", "pipeline name")))
 
 	webservice.Route(webservice.POST("/devops/{devops}/credentials").
 		To(devopsapi.CreateDevOpsProjectCredentialHandler).
-		Doc("add project credential pipeline").
+		Doc("Add project credential pipeline").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Reads(devops.JenkinsCredential{}))
 
 	webservice.Route(webservice.PUT("/devops/{devops}/credentials/{credentials}").
 		To(devopsapi.UpdateDevOpsProjectCredentialHandler).
-		Doc("update project credential pipeline").
+		Doc("Update project credential pipeline").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("credentials", "credential's Id")).
@@ -199,7 +200,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/credentials/{credentials}").
 		To(devopsapi.GetDevOpsProjectCredentialHandler).
-		Doc("get project credential pipeline").
+		Doc("Get project credential pipeline").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("credentials", "credential's Id")).
@@ -210,7 +211,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/devops/{devops}/credentials").
 		To(devopsapi.GetDevOpsProjectCredentialsHandler).
-		Doc("get project credential pipeline").
+		Doc("Get project credential pipeline").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Param(webservice.PathParameter("devops", "devops project's Id")).
 		Param(webservice.PathParameter("credentials", "credential's Id")).

pkg/apis/tenant/v1alpha2/register.go

@@ -23,9 +23,15 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/apiserver/tenant"
+	"kubesphere.io/kubesphere/pkg/models/devops"
+	"kubesphere.io/kubesphere/pkg/params"
+	"net/http"
 )
 
-const GroupName = "tenant.kubesphere.io"
+const (
+	GroupName = "tenant.kubesphere.io"
+	RespOK    = "ok"
+)
 
 var GroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha2"}
 
@@ -87,23 +93,45 @@ 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").
+		Writes([]devops.DevOpsProject{}).
+		Returns(http.StatusOK, RespOK, []devops.DevOpsProject{}).
 		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")).
 		Doc("List the devops projects for the workspace member").
+		Writes([]devops.DevOpsProject{}).
+		Returns(http.StatusOK, RespOK, []devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.POST("/workspaces/{workspace}/devops").
 		To(tenant.CreateDevopsProject).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Doc("Create devops project").
+		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, 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/project_credential.go

@@ -30,46 +30,45 @@ type JenkinsCredential struct {
 	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:""`
-	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, 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