Merge pull request #516 from wansir/api-docs

docs: update api docs

pkg/apis/iam/v1alpha2/register.go

@@ -24,6 +24,7 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"kubesphere.io/kubesphere/pkg/apiserver/iam"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
+	"kubesphere.io/kubesphere/pkg/constants"
 	"kubesphere.io/kubesphere/pkg/errors"
 	"kubesphere.io/kubesphere/pkg/models"
 	"kubesphere.io/kubesphere/pkg/models/iam/policy"
@@ -104,7 +105,6 @@ type DescribeWorkspaceUserResponse struct {
 }
 
 func addWebService(c *restful.Container) error {
-	tags := []string{"IAM"}
 	ws := runtime.NewWebService(GroupVersion)
 
 	ok := "ok"
@@ -114,194 +114,162 @@ func addWebService(c *restful.Container) error {
 		Doc("TokenReview attempts to authenticate a token to a known user. Note: TokenReview requests may be cached by the webhook token authenticator plugin in the kube-apiserver.").
 		Reads(iam.TokenReview{}).
 		Returns(http.StatusOK, ok, iam.TokenReview{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.POST("/login").
 		To(iam.Login).
 		Doc("KubeSphere APIs support token-based authentication via the Authtoken request header. The POST Login API is used to retrieve the authentication token. After the authentication token is obtained, it must be inserted into the Authtoken header for all requests.").
 		Reads(iam.LoginRequest{}).
 		Returns(http.StatusOK, ok, models.Token{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.GET("/users/{user}").
 		To(iam.DescribeUser).
 		Doc("Describe the specified user.").
 		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, models.User{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.POST("/users").
 		To(iam.CreateUser).
 		Doc("Create a user account.").
 		Reads(CreateUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.DELETE("/users/{user}").
 		To(iam.DeleteUser).
 		Doc("Delete a specified user.").
 		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.PUT("/users/{user}").
 		To(iam.UpdateUser).
 		Doc("Update information about the specified user.").
 		Param(ws.PathParameter("user", "username")).
 		Reads(UserUpdateRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.GET("/users/{user}/logs").
 		To(iam.UserLoginLogs).
 		Doc("Retrieve the \"login logs\" for the specified user.").
 		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, LoginLog{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.GET("/users").
 		To(iam.ListUsers).
 		Doc("List all users.").
 		Returns(http.StatusOK, ok, UserList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/groups").
-		To(iam.ListGroups).
-		Doc("List all user groups.").
-		Returns(http.StatusOK, ok, []models.Group{}))
-	ws.Route(ws.GET("/groups/{group}").
-		To(iam.DescribeGroup).
-		Doc("Describe the specified user group.").
-		Param(ws.PathParameter("group", "user group path separated by colon.")).
-		Returns(http.StatusOK, ok, models.Group{}))
-	ws.Route(ws.GET("/groups/{group}/users").
-		To(iam.ListGroupUsers).
-		Doc("List all users in the specified user group.").
-		Param(ws.PathParameter("group", "user group path separated by colon.")).
-		Returns(http.StatusOK, ok, []models.User{}))
-	ws.Route(ws.POST("/groups").
-		To(iam.CreateGroup).
-		Doc("Create a user group.").
-		Reads(models.Group{}).
-		Returns(http.StatusOK, ok, models.Group{}))
-	ws.Route(ws.DELETE("/groups/{group}").
-		To(iam.DeleteGroup).
-		Doc("Delete a user group.").
-		Param(ws.PathParameter("group", "user group path separated by colon.")).
-		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.PUT("/groups/{group}").
-		To(iam.UpdateGroup).
-		Doc("Update information about the user group.").
-		Param(ws.PathParameter("group", "user group path separated by colon.")).
-		Reads(models.Group{}).
-		Returns(http.StatusOK, ok, models.Group{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.IdentityManagementTag}))
 	ws.Route(ws.GET("/users/{user}/roles").
 		To(iam.ListUserRoles).
 		Doc("Retrieve all the roles that are assigned to the user.").
 		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, iam.RoleList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/namespaces/{namespace}/roles").
 		To(iam.ListRoles).
 		Doc("Retrieve the roles that are assigned to the user in the specified namespace.").
 		Param(ws.PathParameter("namespace", "kubernetes namespace")).
 		Returns(http.StatusOK, ok, RoleList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/clusterroles").
 		To(iam.ListClusterRoles).
 		Doc("List all cluster roles.").
 		Returns(http.StatusOK, ok, ClusterRoleList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/namespaces/{namespace}/roles/{role}/users").
 		To(iam.ListRoleUsers).
 		Doc("Retrieve the users that are bound to the role in the specified namespace.").
 		Param(ws.PathParameter("namespace", "kubernetes namespace")).
 		Param(ws.PathParameter("role", "role name")).
 		Returns(http.StatusOK, ok, []models.User{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/namespaces/{namespace}/users").
 		To(iam.ListNamespaceUsers).
 		Doc("List all users in the specified namespace.").
 		Param(ws.PathParameter("namespace", "kubernetes namespace")).
 		Returns(http.StatusOK, ok, []models.User{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/clusterroles/{clusterrole}/users").
 		To(iam.ListClusterRoleUsers).
 		Doc("List all users that are bound to the specified cluster role.").
 		Param(ws.PathParameter("clusterrole", "cluster role name")).
 		Returns(http.StatusOK, ok, UserList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/clusterroles/{clusterrole}/rules").
 		To(iam.ListClusterRoleRules).
 		Doc("List all policy rules of the specified cluster role.").
 		Param(ws.PathParameter("clusterrole", "cluster role name")).
 		Returns(http.StatusOK, ok, []models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/namespaces/{namespace}/roles/{role}/rules").
 		To(iam.ListRoleRules).
 		Doc("List all policy rules of the specified role in the given namespace.").
 		Param(ws.PathParameter("namespace", "kubernetes namespace")).
 		Param(ws.PathParameter("role", "role name")).
 		Returns(http.StatusOK, ok, []models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/devops/{devops}/roles/{role}/rules").
 		To(iam.ListDevopsRoleRules).
 		Doc("List all policy rules of the specified role in the given devops project.").
 		Param(ws.PathParameter("devops", "devops project ID")).
 		Param(ws.PathParameter("role", "devops role name")).
 		Returns(http.StatusOK, ok, []models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/rulesmapping/clusterroles").
 		To(iam.ClusterRulesMapping).
 		Doc("Get the mapping relationships between cluster roles and policy rules.").
 		Returns(http.StatusOK, ok, policy.ClusterRoleRuleMapping).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/rulesmapping/roles").
 		To(iam.RulesMapping).
 		Doc("Get the mapping relationships between namespaced roles and policy rules.").
 		Returns(http.StatusOK, ok, policy.RoleRuleMapping).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/roles").
 		To(iam.ListWorkspaceRoles).
 		Doc("List all workspace roles.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Returns(http.StatusOK, ok, ClusterRoleList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/roles/{role}").
 		To(iam.DescribeWorkspaceRole).
 		Doc("Describe the workspace role.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("role", "workspace role name")).
 		Returns(http.StatusOK, ok, rbacv1.ClusterRole{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/roles/{role}/rules").
 		To(iam.ListWorkspaceRoleRules).
 		Doc("List all policy rules of the specified workspace role.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("role", "workspace role name")).
 		Returns(http.StatusOK, ok, []models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/members").
 		To(iam.ListWorkspaceUsers).
 		Doc("List all members in the specified workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Returns(http.StatusOK, ok, UserList{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.POST("/workspaces/{workspace}/members").
 		To(iam.InviteUser).
 		Doc("Invite members to the workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Reads(InviteUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.DELETE("/workspaces/{workspace}/members/{member}").
 		To(iam.RemoveUser).
 		Doc("Remove members from the workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("member", "username")).
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}").
 		To(iam.DescribeWorkspaceUser).
 		Doc("Describe the specified user in the given workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("member", "username")).
 		Returns(http.StatusOK, ok, DescribeWorkspaceUserResponse{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.AccessManagementTag}))
 	c.Add(ws)
 	return nil
 }

pkg/apis/operations/v1alpha2/register.go

@@ -42,6 +42,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.POST("/nodes/{node}/drainage").
 		To(operations.DrainNode).
+		Deprecate().
 		Doc("Drain node").
 		Param(webservice.PathParameter("node", "node name")).
 		Returns(http.StatusOK, ok, errors.Error{}))
@@ -49,6 +50,7 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.POST("/namespaces/{namespace}/jobs/{job}").
 		To(operations.RerunJob).
 		Doc("Job rerun").
+		Deprecate().
 		Param(webservice.PathParameter("job", "job name")).
 		Param(webservice.PathParameter("namespace", "job's namespace")).
 		Param(webservice.QueryParameter("a", "action")).

pkg/apis/resources/v1alpha2/register.go

@@ -33,6 +33,7 @@ import (
 	"kubesphere.io/kubesphere/pkg/apiserver/routers"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/apiserver/workloadstatuses"
+	"kubesphere.io/kubesphere/pkg/constants"
 	"kubesphere.io/kubesphere/pkg/errors"
 	"kubesphere.io/kubesphere/pkg/models"
 	"kubesphere.io/kubesphere/pkg/models/applications"
@@ -57,71 +58,70 @@ func addWebService(c *restful.Container) error {
 
 	webservice := runtime.NewWebService(GroupVersion)
 
-	tags := []string{"Namespace resources"}
 	ok := "ok"
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/{resources}").
 		To(resources.ListNamespacedResources).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Namespace level resource query").
 		Param(webservice.PathParameter("namespace", "which namespace")).
-		Param(webservice.PathParameter("resources", "namespace level resource type")).
-		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
+		Param(webservice.PathParameter("resources", "namespace level resource type, e.g. pods,jobs,configmaps,services.")).
+		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions,connect multiple conditions with commas, equal symbol for exact query, wave symbol for fuzzy query e.g. name~a").
 			Required(false).
 			DataFormat("key=%s,key~%s")).
-		Param(webservice.QueryParameter(params.PagingParam, "page").
+		Param(webservice.QueryParameter(params.PagingParam, "paging query, e.g. limit=100,page=1").
 			Required(false).
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")).
+		Param(webservice.QueryParameter(params.ReverseParam, "sort parameters, e.g. reverse=true")).
+		Param(webservice.QueryParameter(params.OrderByParam, "sort parameters, e.g. orderBy=createTime")).
 		Returns(http.StatusOK, ok, models.PageableResponse{}))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/jobs/{job}").
 		To(operations.RerunJob).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Rerun job whether the job is complete or not").
 		Param(webservice.PathParameter("job", "job name")).
 		Param(webservice.PathParameter("namespace", "job's namespace")).
 		Param(webservice.QueryParameter("a", "action")).
 		Returns(http.StatusOK, ok, errors.Error{}))
 
-	tags = []string{"Cluster resources"}
-
 	webservice.Route(webservice.GET("/{resources}").
 		To(resources.ListResources).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}).
 		Doc("Cluster level resource query").
-		Param(webservice.PathParameter("resources", "cluster level resource type")).
-		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
+		Param(webservice.PathParameter("resources", "cluster level resource type, e.g. nodes,workspaces,storageclasses,clusterroles.")).
+		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions, connect multiple conditions with commas, equal symbol for exact query, wave symbol for fuzzy query e.g. name~a").
 			Required(false).
 			DataFormat("key=value,key~value").
 			DefaultValue("")).
-		Param(webservice.QueryParameter(params.PagingParam, "page").
+		Param(webservice.QueryParameter(params.PagingParam, "paging query, e.g. limit=100,page=1").
 			Required(false).
 			DataFormat("limit=%d,page=%d").
-			DefaultValue("limit=10,page=1")))
+			DefaultValue("limit=10,page=1")).
+		Param(webservice.QueryParameter(params.ReverseParam, "sort parameters, e.g. reverse=true")).
+		Param(webservice.QueryParameter(params.OrderByParam, "sort parameters, e.g. orderBy=createTime")))
 
 	webservice.Route(webservice.POST("/nodes/{node}/drainage").
 		To(operations.DrainNode).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}).
 		Doc("Drain node").
 		Param(webservice.PathParameter("node", "node name")).
 		Returns(http.StatusOK, ok, errors.Error{}))
 
-	tags = []string{"Applications"}
-
 	webservice.Route(webservice.GET("/applications").
 		To(resources.ListApplication).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Doc("List all applications deployed in the cluster").
-		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}).
+		Doc("List applications in cluster").
+		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions, connect multiple conditions with commas, equal symbol for exact query, wave symbol for fuzzy query e.g. name~a").
 			Required(false).
 			DataFormat("key=value,key~value").
 			DefaultValue("")).
-		Param(webservice.QueryParameter("cluster_id", "cluster ID")).
-		Param(webservice.QueryParameter("runtime_id", "runtime ID")).
-		Param(webservice.QueryParameter(params.PagingParam, "page").
+		Param(webservice.QueryParameter("cluster_id", "equivalent to application unique ID")).
+		Param(webservice.QueryParameter("runtime_id", "runtime id initialization when namespace is created, means which namespace")).
+		Param(webservice.QueryParameter(params.PagingParam, "paging query, e.g. limit=100,page=1").
 			Required(false).
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")))
@@ -129,14 +129,14 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.GET("/namespaces/{namespace}/applications").
 		To(resources.ListNamespacedApplication).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("List all applications within the specified namespace").
-		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
+		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions, connect multiple conditions with commas, equal symbol for exact query, wave symbol for fuzzy query e.g. name~a").
 			Required(false).
 			DataFormat("key=value,key~value").
 			DefaultValue("")).
-		Param(webservice.PathParameter("namespace", "namespace name")).
-		Param(webservice.QueryParameter(params.PagingParam, "page").
+		Param(webservice.PathParameter("namespace", "namespace")).
+		Param(webservice.QueryParameter(params.PagingParam, "paging query, e.g. limit=100,page=1").
 			Required(false).
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")))
@@ -144,7 +144,7 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.GET("/namespaces/{namespace}/applications/{application}").
 		To(resources.DescribeApplication).
 		Returns(http.StatusOK, ok, applications.Application{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Describe the specified application of the namespace").
 		Param(webservice.PathParameter("namespace", "namespace name")).
 		Param(webservice.PathParameter("application", "application ID")))
@@ -152,7 +152,7 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.POST("/namespaces/{namespace}/applications").
 		To(resources.DeployApplication).
 		Doc("Deploy a new application").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Reads(openpitrix.CreateClusterRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Param(webservice.PathParameter("namespace", "namespace name")))
@@ -160,18 +160,16 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.DELETE("/namespaces/{namespace}/applications/{application}").
 		To(resources.DeleteApplication).
 		Doc("Delete the specified application").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Param(webservice.PathParameter("namespace", "namespace name")).
 		Param(webservice.PathParameter("application", "application ID")))
 
-	tags = []string{"User resources"}
-
 	webservice.Route(webservice.GET("/users/{user}/kubectl").
 		To(resources.GetKubectl).
 		Doc("get user's kubectl pod").
 		Param(webservice.PathParameter("user", "username")).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.UserResourcesTag}).
 		Returns(http.StatusOK, ok, models.PodInfo{}))
 
 	webservice.Route(webservice.GET("/users/{user}/kubeconfig").
@@ -180,66 +178,56 @@ func addWebService(c *restful.Container) error {
 		Doc("get users' kubeconfig").
 		Param(webservice.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, "").
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-
-	tags = []string{"Components"}
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.UserResourcesTag}))
 
 	webservice.Route(webservice.GET("/components").
 		To(components.GetComponents).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ComponentStatusTag}).
 		Doc("List the system components.").
 		Returns(http.StatusOK, ok, map[string]models.Component{}))
 	webservice.Route(webservice.GET("/components/{component}").
 		To(components.GetComponentStatus).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ComponentStatusTag}).
 		Doc("Describe the specified system component.").
 		Param(webservice.PathParameter("component", "component name")).
 		Returns(http.StatusOK, ok, models.Component{}))
 	webservice.Route(webservice.GET("/componenthealth").
 		To(components.GetSystemHealthStatus).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ComponentStatusTag}).
 		Doc("Get the health status of system components.").
 		Returns(http.StatusOK, ok, map[string]int{}))
 
-	tags = []string{"Quotas"}
-
 	webservice.Route(webservice.GET("/quotas").
 		To(quotas.GetClusterQuotas).
-		Deprecate().
 		Doc("get whole cluster's resource usage").
 		Returns(http.StatusOK, ok, models.ResourceQuota{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}))
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/quotas").
 		Doc("get specified namespace's resource quota and usage").
 		Param(webservice.PathParameter("namespace", "namespace's name")).
 		Returns(http.StatusOK, ok, models.ResourceQuota{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		To(quotas.GetNamespaceQuotas))
 
-	tags = []string{"Registries"}
-
 	webservice.Route(webservice.POST("registry/verify").
 		To(registries.RegistryVerify).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.VerificationTag}).
 		Doc("docker registry verify").
 		Reads(registriesmodel.AuthInfo{}).
 		Returns(http.StatusOK, ok, errors.Error{}))
 
-	tags = []string{"Git"}
 	webservice.Route(webservice.POST("git/verify").
-		To(
-			git.GitReadVerify).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		To(git.GitReadVerify).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.VerificationTag}).
 		Doc("Verify that the kubernetes secret has read access to the git repository").
 		Reads(gitmodel.AuthInfo{}).
 		Returns(http.StatusOK, ok, errors.Error{}),
 	)
-	tags = []string{"Revision"}
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/daemonsets/{daemonset}/revisions/{revision}").
 		To(revisions.GetDaemonSetRevision).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Handle daemonset operation").
 		Param(webservice.PathParameter("daemonset", "daemonset's name")).
 		Param(webservice.PathParameter("namespace", "daemonset's namespace")).
@@ -247,7 +235,7 @@ func addWebService(c *restful.Container) error {
 		Returns(http.StatusOK, ok, appsv1.DaemonSet{}))
 	webservice.Route(webservice.GET("/namespaces/{namespace}/deployments/{deployment}/revisions/{revision}").
 		To(revisions.GetDeployRevision).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Handle deployment operation").
 		Param(webservice.PathParameter("deployment", "deployment's name")).
 		Param(webservice.PathParameter("namespace", "deployment's namespace")).
@@ -255,56 +243,52 @@ func addWebService(c *restful.Container) error {
 		Returns(http.StatusOK, ok, appsv1.ReplicaSet{}))
 	webservice.Route(webservice.GET("/namespaces/{namespace}/statefulsets/{statefulset}/revisions/{revision}").
 		To(revisions.GetStatefulSetRevision).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Doc("Handle statefulset operation").
 		Param(webservice.PathParameter("statefulset", "statefulset's name")).
 		Param(webservice.PathParameter("namespace", "statefulset's namespace")).
 		Param(webservice.PathParameter("revision", "statefulset's revision")).
 		Returns(http.StatusOK, ok, appsv1.StatefulSet{}))
 
-	tags = []string{"Router"}
-
 	webservice.Route(webservice.GET("/routers").
 		To(routers.GetAllRouters).
 		Doc("List all routers").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}).
 		Returns(http.StatusOK, ok, corev1.Service{}))
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/router").
 		To(routers.GetRouter).
 		Doc("List router of a specified project").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Param(webservice.PathParameter("namespace", "name of the project")))
 
 	webservice.Route(webservice.DELETE("/namespaces/{namespace}/router").
 		To(routers.DeleteRouter).
 		Doc("List router of a specified project").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Param(webservice.PathParameter("namespace", "name of the project")))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/router").
 		To(routers.CreateRouter).
 		Doc("Create a router for a specified project").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Param(webservice.PathParameter("namespace", "name of the project")))
 
 	webservice.Route(webservice.PUT("/namespaces/{namespace}/router").
 		To(routers.UpdateRouter).
 		Doc("Update a router for a specified project").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Param(webservice.PathParameter("namespace", "name of the project")))
 
-	tags = []string{"WorkloadStatus"}
-
 	webservice.Route(webservice.GET("/abnormalworkloads").
 		Doc("get abnormal workloads' count of whole cluster").
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.ClusterResourcesTag}).
 		Returns(http.StatusOK, ok, status.WorkLoadStatus{}).
 		To(workloadstatuses.GetClusterAbnormalWorkloads))
 	webservice.Route(webservice.GET("/namespaces/{namespace}/abnormalworkloads").
 		Doc("get abnormal workloads' count of specified namespace").
 		Param(webservice.PathParameter("namespace", "the name of namespace")).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.NamespaceResourcesTag}).
 		Returns(http.StatusOK, ok, status.WorkLoadStatus{}).
 		To(workloadstatuses.GetNamespacedAbnormalWorkloads))
 

pkg/apis/tenant/v1alpha2/register.go

@@ -25,6 +25,7 @@ import (
 	"kubesphere.io/kubesphere/pkg/apis/tenant/v1alpha1"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/apiserver/tenant"
+	"kubesphere.io/kubesphere/pkg/constants"
 	"kubesphere.io/kubesphere/pkg/models/devops"
 	"kubesphere.io/kubesphere/pkg/params"
 	"kubesphere.io/kubesphere/pkg/simple/client/elasticsearch"
@@ -48,7 +49,6 @@ var (
 )
 
 func addWebService(c *restful.Container) error {
-	tags := []string{"Tenant"}
 	ok := "ok"
 	ws := runtime.NewWebService(GroupVersion)
 
@@ -56,57 +56,57 @@ func addWebService(c *restful.Container) error {
 		To(tenant.ListWorkspaces).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Doc("List workspace by user").
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}").
 		To(tenant.DescribeWorkspace).
 		Doc("Describe workspace").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Returns(http.StatusOK, ok, v1alpha1.Workspace{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/rules").
 		To(tenant.ListWorkspaceRules).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Doc("List the rules for the current user").
 		Returns(http.StatusOK, ok, models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/namespaces/{namespace}/rules").
 		To(tenant.ListNamespaceRules).
 		Param(ws.PathParameter("namespace", "namespace")).
 		Doc("List the rules for the current user").
 		Returns(http.StatusOK, ok, models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/devops/{devops}/rules").
 		To(tenant.ListDevopsRules).
 		Param(ws.PathParameter("devops", "devops project id")).
 		Doc("List the rules for the current user").
 		Returns(http.StatusOK, ok, models.SimpleRule{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/namespaces").
 		To(tenant.ListNamespaces).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Doc("List the namespaces for the current user").
 		Returns(http.StatusOK, ok, []v1.Namespace{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}/namespaces").
 		To(tenant.ListNamespacesByUsername).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("member", "workspace member's username")).
 		Doc("List the namespaces for the workspace member").
 		Returns(http.StatusOK, ok, []v1.Namespace{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.POST("/workspaces/{workspace}/namespaces").
 		To(tenant.CreateNamespace).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Doc("Create namespace").
 		Returns(http.StatusOK, ok, []v1.Namespace{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.DELETE("/workspaces/{workspace}/namespaces/{namespace}").
 		To(tenant.DeleteNamespace).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("namespace", "namespace")).
 		Doc("Delete namespace").
 		Returns(http.StatusOK, ok, errors.Error{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 
 	ws.Route(ws.GET("/workspaces/{workspace}/devops").
 		To(tenant.ListDevopsProjects).
@@ -119,7 +119,7 @@ func addWebService(c *restful.Container) error {
 			Required(false).
 			DataFormat("key=%s,key~%s")).
 		Doc("List devops projects for the current user").
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}/devops").
 		To(tenant.ListDevopsProjectsByUsername).
 		Param(ws.PathParameter("workspace", "workspace name")).
@@ -133,21 +133,21 @@ func addWebService(c *restful.Container) error {
 			DataFormat("key=%s,key~%s")).
 		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Doc("List the devops projects for the workspace member").
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	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))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.DELETE("/workspaces/{workspace}/devops/{devops}").
 		To(tenant.DeleteDevopsProject).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("devops", "devops project id")).
 		Doc("Delete devops project").
 		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}))
 	ws.Route(ws.GET("/logs").
 		To(tenant.LogQuery).
 		Doc("Query cluster-level logs in a multi-tenants environment").
@@ -169,7 +169,7 @@ func addWebService(c *restful.Container) error {
 		Param(ws.QueryParameter("sort", "Sort log by time. One of acs, desc.").DataType("string").DefaultValue("desc").Required(false)).
 		Param(ws.QueryParameter("from", "Beginning index of result to return. Use this option together with size.").DataType("integer").DefaultValue("0").Required(false)).
 		Param(ws.QueryParameter("size", "Size of result to return.").DataType("integer").DefaultValue("10").Required(false)).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Metadata(restfulspec.KeyOpenAPITags, []string{constants.TenantResourcesTag}).
 		Writes(esclient.Response{}).
 		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).

pkg/constants/constants.go

@@ -48,6 +48,15 @@ const (
 	DevopsReporter                 = "reporter"
 
 	UserNameHeader = "X-Token-Username"
+
+	TenantResourcesTag    = "Tenant Resources"
+	IdentityManagementTag = "Identity Management"
+	AccessManagementTag   = "Access Management"
+	NamespaceResourcesTag = "Namespace Resources"
+	ClusterResourcesTag   = "Cluster Resources"
+	ComponentStatusTag    = "Component Status"
+	VerificationTag       = "Verification"
+	UserResourcesTag      = "User Resources"
 )
 
 var (

pkg/controller/workspace/workspace_controller.go

@@ -132,12 +132,6 @@ func (r *ReconcileWorkspace) Reconcile(request reconcile.Request) (reconcile.Res
 		// The object is being deleted
 		if sliceutil.HasString(instance.ObjectMeta.Finalizers, finalizer) {
 			// our finalizer is present, so lets handle our external dependency
-			if err := r.deleteGroup(instance); err != nil {
-				// if fail to delete the external dependency here, return with error
-				// so that it can be retried
-				return reconcile.Result{}, err
-			}
-
 			if err := r.deleteDevOpsProjects(instance); err != nil {
 				return reconcile.Result{}, err
 			}
@@ -167,10 +161,6 @@ func (r *ReconcileWorkspace) Reconcile(request reconcile.Request) (reconcile.Res
 		return reconcile.Result{}, err
 	}
 
-	//if err = r.createGroup(instance); err != nil {
-	//	return reconcile.Result{}, err
-	//}
-
 	if err = r.createWorkspaceRoleBindings(instance); err != nil {
 		return reconcile.Result{}, err
 	}

tools/cmd/doc-gen/main.go

@@ -27,6 +27,7 @@ import (
 	"github.com/go-openapi/spec"
 	"io/ioutil"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
+	"kubesphere.io/kubesphere/pkg/constants"
 	"log"
 	// Install apis
 	_ "kubesphere.io/kubesphere/pkg/apis/devops/install"
@@ -62,6 +63,33 @@ func generateSwaggerJson() {
 
 	swagger := restfulspec.BuildSwagger(config)
 
+	swagger.Info.Extensions = make(spec.Extensions)
+	swagger.Info.Extensions.Add("x-tagGroups", []struct {
+		Name string   `json:"name"`
+		Tags []string `json:"tags"`
+	}{
+		{
+			Name: "IAM",
+			Tags: []string{constants.IdentityManagementTag, constants.AccessManagementTag},
+		},
+		{
+			Name: "Resources",
+			Tags: []string{constants.ClusterResourcesTag, constants.NamespaceResourcesTag, constants.UserResourcesTag},
+		},
+		{
+			Name: "Monitoring",
+			Tags: []string{constants.ComponentStatusTag},
+		},
+		{
+			Name: "Tenant",
+			Tags: []string{constants.TenantResourcesTag},
+		},
+		{
+			Name: "Other",
+			Tags: []string{constants.VerificationTag},
+		},
+	})
+
 	data, _ := json.Marshal(swagger)
 	err := ioutil.WriteFile(output, data, 420)
 	if err != nil {