update api docs (#490)

* update api docs

Signed-off-by: hongming <talonwan@yunify.com>

* fix: kube-apiserver host in kubeconfig

Signed-off-by: hongming <talonwan@yunify.com>

pkg/apis/iam/v1alpha2/register.go

@@ -121,10 +121,10 @@ func addWebService(c *restful.Container) error {
 		Reads(iam.LoginRequest{}).
 		Returns(http.StatusOK, ok, models.Token{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/users/{username}").
+	ws.Route(ws.GET("/users/{user}").
 		To(iam.DescribeUser).
-		Doc("Describes the specified user.").
-		Param(ws.PathParameter("username", "username")).
+		Doc("Describe the specified user.").
+		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, models.User{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.POST("/users").
@@ -133,23 +133,23 @@ func addWebService(c *restful.Container) error {
 		Reads(CreateUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.DELETE("/users/{username}").
+	ws.Route(ws.DELETE("/users/{user}").
 		To(iam.DeleteUser).
 		Doc("Remove a specified user.").
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.PUT("/users/{username}").
+	ws.Route(ws.PUT("/users/{user}").
 		To(iam.UpdateUser).
 		Doc("Updates information about the specified user.").
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("user", "username")).
 		Reads(UserUpdateRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/users/{username}/log").
-		To(iam.UserLoginLog).
+	ws.Route(ws.GET("/users/{user}/logs").
+		To(iam.UserLoginLogs).
 		Doc("This method is used to retrieve the \"login logs\" for the specified user.").
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, LoginLog{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/users").
@@ -160,43 +160,39 @@ func addWebService(c *restful.Container) error {
 	ws.Route(ws.GET("/groups").
 		To(iam.ListGroups).
 		Doc("List all user groups.").
-		Returns(http.StatusOK, ok, []models.Group{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/groups/{path}").
+		Returns(http.StatusOK, ok, []models.Group{}))
+	ws.Route(ws.GET("/groups/{group}").
 		To(iam.DescribeGroup).
-		Doc("Describes the specified user group.").
-		Param(ws.PathParameter("path", "user group path separated by colon.")).
-		Returns(http.StatusOK, ok, models.Group{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/groups/{path}/users").
+		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("path", "user group path separated by colon.")).
-		Returns(http.StatusOK, ok, []models.User{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
+		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{}).
-		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.DELETE("/groups/{path}").
+		Returns(http.StatusOK, ok, models.Group{}))
+	ws.Route(ws.DELETE("/groups/{group}").
 		To(iam.DeleteGroup).
 		Doc("Delete a user group.").
-		Param(ws.PathParameter("path", "user group path separated by colon.")).
+		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/{path}").
+	ws.Route(ws.PUT("/groups/{group}").
 		To(iam.UpdateGroup).
 		Doc("Updates information about the user group.").
-		Param(ws.PathParameter("path", "user group path separated by colon.")).
+		Param(ws.PathParameter("group", "user group path separated by colon.")).
 		Reads(models.Group{}).
 		Returns(http.StatusOK, ok, models.Group{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/users/{username}/roles").
+	ws.Route(ws.GET("/users/{user}/roles").
 		To(iam.ListUserRoles).
 		Doc("This method is used to retrieve all the roles that are assigned to the user.").
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, iam.RoleList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/namespaces/{namespace}/roles").
@@ -267,7 +263,7 @@ func addWebService(c *restful.Container) error {
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/workspaces/{workspace}/roles/{role}").
 		To(iam.DescribeWorkspaceRole).
-		Doc("Describes the workspace role.").
+		Doc("Describe the workspace role.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("role", "workspace role name")).
 		Returns(http.StatusOK, ok, rbacv1.ClusterRole{}).
@@ -292,18 +288,18 @@ func addWebService(c *restful.Container) error {
 		Reads(InviteUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.DELETE("/workspaces/{workspace}/members/{username}").
+	ws.Route(ws.DELETE("/workspaces/{workspace}/members/{member}").
 		To(iam.RemoveUser).
 		Doc("Remove members from workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("member", "username")).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/workspaces/{workspace}/members/{username}").
+	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}").
 		To(iam.DescribeWorkspaceUser).
-		Doc("Describes the specified user.").
+		Doc("Describe the specified user.").
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Param(ws.PathParameter("username", "username")).
+		Param(ws.PathParameter("member", "username")).
 		Returns(http.StatusOK, ok, DescribeWorkspaceUserResponse{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	c.Add(ws)

pkg/apis/operations/v1alpha2/register.go

@@ -19,7 +19,6 @@ package v1alpha2
 
 import (
 	"github.com/emicklei/go-restful"
-	"github.com/emicklei/go-restful-openapi"
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"kubesphere.io/kubesphere/pkg/apiserver/operations"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
@@ -38,20 +37,17 @@ var (
 
 func addWebService(c *restful.Container) error {
 
-	tags := []string{"Operations"}
 	ok := "ok"
 	webservice := runtime.NewWebService(GroupVersion)
 
 	webservice.Route(webservice.POST("/nodes/{node}/drainage").
 		To(operations.DrainNode).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Drain node").
 		Param(webservice.PathParameter("node", "node name")).
 		Returns(http.StatusOK, ok, errors.Error{}))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/jobs/{job}").
 		To(operations.RerunJob).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Job rerun").
 		Param(webservice.PathParameter("job", "job name")).
 		Param(webservice.PathParameter("namespace", "job's namespace")).

pkg/apis/resources/v1alpha2/register.go

@@ -25,6 +25,7 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"kubesphere.io/kubesphere/pkg/apiserver/components"
 	"kubesphere.io/kubesphere/pkg/apiserver/git"
+	"kubesphere.io/kubesphere/pkg/apiserver/operations"
 	"kubesphere.io/kubesphere/pkg/apiserver/quotas"
 	"kubesphere.io/kubesphere/pkg/apiserver/registries"
 	"kubesphere.io/kubesphere/pkg/apiserver/resources"
@@ -74,6 +75,15 @@ func addWebService(c *restful.Container) error {
 			DefaultValue("limit=10,page=1")).
 		Returns(http.StatusOK, ok, models.PageableResponse{}))
 
+	webservice.Route(webservice.POST("/namespaces/{namespace}/jobs/{job}").
+		To(operations.RerunJob).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		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}").
@@ -91,6 +101,15 @@ func addWebService(c *restful.Container) error {
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")))
 
+	webservice.Route(webservice.POST("/nodes/{node}/drainage").
+		To(operations.DrainNode).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Doc("Drain node").
+		Param(webservice.PathParameter("node", "node name")).
+		Returns(http.StatusOK, ok, errors.Error{}))
+
+	c.Add(webservice)
+
 	tags = []string{"Applications"}
 
 	webservice.Route(webservice.GET("/applications").
@@ -124,13 +143,13 @@ func addWebService(c *restful.Container) error {
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")))
 
-	webservice.Route(webservice.GET("/namespaces/{namespace}/applications/{cluster_id}").
+	webservice.Route(webservice.GET("/namespaces/{namespace}/applications/{application}").
 		To(resources.DescribeApplication).
 		Returns(http.StatusOK, ok, applications.Application{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Describe application").
 		Param(webservice.PathParameter("namespace", "namespace name")).
-		Param(webservice.PathParameter("cluster_id", "application id")))
+		Param(webservice.PathParameter("application", "application id")))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/applications").
 		To(resources.DeployApplication).
@@ -140,28 +159,28 @@ func addWebService(c *restful.Container) error {
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Param(webservice.PathParameter("namespace", "namespace name")))
 
-	webservice.Route(webservice.DELETE("/namespaces/{namespace}/applications/{cluster_id}").
+	webservice.Route(webservice.DELETE("/namespaces/{namespace}/applications/{application}").
 		To(resources.DeleteApplication).
 		Doc("Delete application").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Param(webservice.PathParameter("namespace", "namespace name")).
-		Param(webservice.PathParameter("cluster_id", "application id")))
+		Param(webservice.PathParameter("application", "application id")))
 
 	tags = []string{"User resources"}
 
-	webservice.Route(webservice.GET("/users/{username}/kubectl").
+	webservice.Route(webservice.GET("/users/{user}/kubectl").
 		To(resources.GetKubectl).
 		Doc("get user's kubectl pod").
-		Param(webservice.PathParameter("username", "username")).
+		Param(webservice.PathParameter("user", "username")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Returns(http.StatusOK, ok, models.PodInfo{}))
 
-	webservice.Route(webservice.GET("/users/{username}/kubeconfig").
+	webservice.Route(webservice.GET("/users/{user}/kubeconfig").
 		Produces("text/plain").
 		To(resources.GetKubeconfig).
 		Doc("get users' kubeconfig").
-		Param(webservice.PathParameter("username", "username")).
+		Param(webservice.PathParameter("user", "username")).
 		Returns(http.StatusOK, ok, "").
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 
@@ -178,7 +197,7 @@ func addWebService(c *restful.Container) error {
 		Doc("").
 		Param(webservice.PathParameter("component", "component name")).
 		Returns(http.StatusOK, ok, models.Component{}))
-	webservice.Route(webservice.GET("/health").
+	webservice.Route(webservice.GET("/componenthealth").
 		To(components.GetSystemHealthStatus).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("").
@@ -202,7 +221,7 @@ func addWebService(c *restful.Container) error {
 
 	tags = []string{"Registries"}
 
-	webservice.Route(webservice.POST("registries/verify").
+	webservice.Route(webservice.POST("registry/verify").
 		To(registries.RegistryVerify).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("docker registry verify").
@@ -279,17 +298,17 @@ func addWebService(c *restful.Container) error {
 
 	tags = []string{"WorkloadStatus"}
 
-	webservice.Route(webservice.GET("/workloadstatuses").
+	webservice.Route(webservice.GET("/abnormalworkloads").
 		Doc("get abnormal workloads' count of whole cluster").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Returns(http.StatusOK, ok, status.WorkLoadStatus{}).
-		To(workloadstatuses.GetClusterResourceStatus))
-	webservice.Route(webservice.GET("/namespaces/{namespace}/workloadstatuses").
+		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).
 		Returns(http.StatusOK, ok, status.WorkLoadStatus{}).
-		To(workloadstatuses.GetNamespacesResourceStatus))
+		To(workloadstatuses.GetNamespacedAbnormalWorkloads))
 
 	c.Add(webservice)
 

pkg/apis/tenant/v1alpha2/register.go

@@ -87,10 +87,10 @@ func addWebService(c *restful.Container) error {
 		Doc("List the namespaces for the current user").
 		Returns(http.StatusOK, ok, []v1.Namespace{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/workspaces/{workspace}/members/{username}/namespaces").
+	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}/namespaces").
 		To(tenant.ListNamespacesByUsername).
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Param(ws.PathParameter("username", "workspace member's username")).
+		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))
@@ -120,10 +120,10 @@ func addWebService(c *restful.Container) error {
 			DataFormat("key=%s,key~%s")).
 		Doc("List devops projects for the current user").
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/workspaces/{workspace}/members/{username}/devops").
+	ws.Route(ws.GET("/workspaces/{workspace}/members/{member}/devops").
 		To(tenant.ListDevopsProjectsByUsername).
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Param(ws.PathParameter("username", "workspace member's username")).
+		Param(ws.PathParameter("member", "workspace member's username")).
 		Param(ws.QueryParameter(params.PagingParam, "page").
 			Required(false).
 			DataFormat("limit=%d,page=%d").
@@ -141,14 +141,14 @@ func addWebService(c *restful.Container) error {
 		Reads(devops.DevOpsProject{}).
 		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.DELETE("/workspaces/{workspace}/devops/{id}").
+	ws.Route(ws.DELETE("/workspaces/{workspace}/devops/{devops}").
 		To(tenant.DeleteDevopsProject).
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Param(ws.PathParameter("id", "devops project id")).
+		Param(ws.PathParameter("devops", "devops project id")).
 		Doc("Delete devops project").
 		Returns(http.StatusOK, RespOK, devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
-	ws.Route(ws.GET("/logging").
+	ws.Route(ws.GET("/logs").
 		To(tenant.LogQuery).
 		Doc("Query cluster-level logs in a multi-tenants environment").
 		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).