Merge branch 'master' into devops-docs

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

# Conflicts:
#	pkg/apis/tenant/v1alpha2/register.go

pkg/apis/iam/v1alpha2/register.go

@@ -28,6 +28,7 @@ import (
 	"kubesphere.io/kubesphere/pkg/models"
 	"kubesphere.io/kubesphere/pkg/models/iam/policy"
 	"net/http"
+	"time"
 )
 
 const GroupName = "iam.kubesphere.io"
@@ -39,15 +40,74 @@ var (
 	AddToContainer    = WebServiceBuilder.AddToContainer
 )
 
+type UserUpdateRequest struct {
+	Username        string `json:"username" description:"username"`
+	Email           string `json:"email" description:"email address"`
+	Lang            string `json:"lang" description:"user's language setting, default is zh-CN"`
+	Description     string `json:"description" description:"user's description"`
+	Password        string `json:"password,omitempty" description:"this is necessary if you need to change your password"`
+	CurrentPassword string `json:"current_password,omitempty" description:"this is necessary if you need to change your password"`
+	ClusterRole     string `json:"cluster_role" description:"user's cluster role"`
+}
+
+type CreateUserRequest struct {
+	Username    string `json:"username" description:"username"`
+	Email       string `json:"email" description:"email address"`
+	Lang        string `json:"lang,omitempty" description:"user's language setting, default is zh-CN"`
+	Description string `json:"description" description:"user's description"`
+	Password    string `json:"password" description:"password'"`
+	ClusterRole string `json:"cluster_role" description:"user's cluster role"`
+}
+
+type UserList struct {
+	Items []struct {
+		Username      string    `json:"username" description:"username"`
+		Email         string    `json:"email" description:"email address"`
+		Lang          string    `json:"lang,omitempty" description:"user's language setting, default is zh-CN"`
+		Description   string    `json:"description" description:"user's description"`
+		ClusterRole   string    `json:"cluster_role" description:"user's cluster role"`
+		CreateTime    time.Time `json:"create_time" description:"user creation time"`
+		LastLoginTime time.Time `json:"last_login_time" description:"last login time"`
+	} `json:"items" description:"paging data"`
+	TotalCount int `json:"total_count" description:"total count"`
+}
+
+type ClusterRoleList struct {
+	Items      []rbacv1.ClusterRole `json:"items" description:"paging data"`
+	TotalCount int                  `json:"total_count" description:"total count"`
+}
+
+type LoginLog struct {
+	LoginTime string `json:"login_time" description:"last login time"`
+	LoginIP   string `json:"login_ip" description:"last login ip"`
+}
+
+type RoleList struct {
+	Items      []rbacv1.Role `json:"items" description:"paging data"`
+	TotalCount int           `json:"total_count" description:"total count"`
+}
+
+type InviteUserRequest struct {
+	Username      string `json:"username" description:"username"`
+	WorkspaceRole string `json:"workspace_role" description:"user's workspace role'"`
+}
+
+type DescribeWorkspaceUserResponse struct {
+	Username      string    `json:"username" description:"username"`
+	Email         string    `json:"email" description:"email address"`
+	Lang          string    `json:"lang" description:"user's language setting, default is zh-CN"`
+	Description   string    `json:"description" description:"user's description"`
+	ClusterRole   string    `json:"cluster_role" description:"user's cluster role"`
+	WorkspaceRole string    `json:"workspace_role" description:"user's workspace role"`
+	CreateTime    time.Time `json:"create_time" description:"user creation time"`
+	LastLoginTime time.Time `json:"last_login_time" description:"last login time"`
+}
+
 func addWebService(c *restful.Container) error {
 	tags := []string{"IAM"}
 	ws := runtime.NewWebService(GroupVersion)
 
 	ok := "ok"
-	pageableUserList := struct {
-		Items      []models.User `json:"items"`
-		TotalCount int           `json:"total_count"`
-	}{}
 
 	ws.Route(ws.POST("/authenticate").
 		To(iam.TokenReviewHandler).
@@ -70,7 +130,7 @@ func addWebService(c *restful.Container) error {
 	ws.Route(ws.POST("/users").
 		To(iam.CreateUser).
 		Doc("Create a user account.").
-		Reads(models.User{}).
+		Reads(CreateUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.DELETE("/users/{name}").
@@ -83,22 +143,19 @@ func addWebService(c *restful.Container) error {
 		To(iam.UpdateUser).
 		Doc("Updates information about the specified user.").
 		Param(ws.PathParameter("name", "username")).
-		Reads(models.User{}).
+		Reads(UserUpdateRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/users/{name}/log").
 		To(iam.UserLoginLog).
 		Doc("This method is used to retrieve the \"login logs\" for the specified user.").
 		Param(ws.PathParameter("name", "username")).
-		Returns(http.StatusOK, ok, struct {
-			LoginTime string `json:"login_time"`
-			LoginIP   string `json:"login_ip"`
-		}{}).
+		Returns(http.StatusOK, ok, LoginLog{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/users").
 		To(iam.ListUsers).
 		Doc("List all users.").
-		Returns(http.StatusOK, ok, pageableUserList).
+		Returns(http.StatusOK, ok, UserList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/groups").
 		To(iam.ListGroups).
@@ -146,18 +203,12 @@ func addWebService(c *restful.Container) error {
 		To(iam.ListRoles).
 		Doc("This method is used to retrieve the roles that are assigned to the user in the specified namespace.").
 		Param(ws.PathParameter("namespace", "kubernetes namespace")).
-		Returns(http.StatusOK, ok, struct {
-			Items      []rbacv1.Role `json:"items"`
-			TotalCount int           `json:"total_count"`
-		}{}).
+		Returns(http.StatusOK, ok, RoleList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/clusterroles").
 		To(iam.ListClusterRoles).
 		Doc("List all cluster roles.").
-		Returns(http.StatusOK, ok, struct {
-			Items      []rbacv1.ClusterRole `json:"items"`
-			TotalCount int                  `json:"total_count"`
-		}{}).
+		Returns(http.StatusOK, ok, ClusterRoleList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/namespaces/{namespace}/roles/{role}/users").
 		To(iam.ListRoleUsers).
@@ -176,7 +227,7 @@ func addWebService(c *restful.Container) error {
 		To(iam.ListClusterRoleUsers).
 		Doc("List all users that are bind the cluster role.").
 		Param(ws.PathParameter("clusterrole", "cluster role name")).
-		Returns(http.StatusOK, ok, pageableUserList).
+		Returns(http.StatusOK, ok, UserList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/clusterroles/{clusterrole}/rules").
 		To(iam.ListClusterRoleRules).
@@ -212,10 +263,7 @@ func addWebService(c *restful.Container) error {
 		To(iam.ListWorkspaceRoles).
 		Doc("List all workspace roles.").
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Returns(http.StatusOK, ok, struct {
-			Items      []rbacv1.ClusterRole `json:"items"`
-			TotalCount int                  `json:"total_count"`
-		}{}).
+		Returns(http.StatusOK, ok, ClusterRoleList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/workspaces/{workspace}/roles/{role}").
 		To(iam.DescribeWorkspaceRole).
@@ -235,13 +283,13 @@ func addWebService(c *restful.Container) error {
 		To(iam.ListWorkspaceUsers).
 		Doc("List all members in the specified workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Returns(http.StatusOK, ok, pageableUserList).
+		Returns(http.StatusOK, ok, UserList{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.POST("/workspaces/{workspace}/members").
 		To(iam.InviteUser).
 		Doc("Invite members to a workspace.").
 		Param(ws.PathParameter("workspace", "workspace name")).
-		Reads(models.User{}).
+		Reads(InviteUserRequest{}).
 		Returns(http.StatusOK, ok, errors.Error{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.DELETE("/workspaces/{workspace}/members/{username}").
@@ -256,7 +304,7 @@ func addWebService(c *restful.Container) error {
 		Doc("Describes the specified user.").
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("username", "username")).
-		Returns(http.StatusOK, ok, models.User{}).
+		Returns(http.StatusOK, ok, DescribeWorkspaceUserResponse{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	c.Add(ws)
 	return nil

pkg/apis/logging/v1alpha2/register.go

@@ -24,9 +24,16 @@ import (
 	"kubesphere.io/kubesphere/pkg/apiserver/logging"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/filter"
+	"kubesphere.io/kubesphere/pkg/models/log"
+	esclient "kubesphere.io/kubesphere/pkg/simple/client/elasticsearch"
+	fluentbitclient "kubesphere.io/kubesphere/pkg/simple/client/fluentbit"
+	"net/http"
 )
 
-const GroupName = "logging.kubesphere.io"
+const (
+	GroupName = "logging.kubesphere.io"
+	RespOK    = "ok"
+)
 
 var GroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha2"}
 
@@ -41,174 +48,196 @@ func addWebService(c *restful.Container) error {
 
 	ws.Route(ws.GET("/cluster").To(logging.LoggingQueryCluster).
 		Filter(filter.Logging).
-		Doc("cluster level log query").
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("workspaces", "workspaces specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workspace_query", "workspace query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("namespaces", "namespaces specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("namespace_query", "namespace query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workloads", "workloads specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workload_query", "workload query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pods", "pods specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pod_query", "pod query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("containers", "containers specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("container_query", "container query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against the cluster.").
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("workspaces", "List of workspaces the query will perform against, eg. wk-one,wk-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workspace_query", "List of keywords for filtering workspaces. Workspaces whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("namespaces", "List of namespaces the query will perform against, eg. ns-one,ns-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("namespace_query", "List of keywords for filtering namespaces. Namespaces whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workloads", "List of workloads the query will perform against, eg. wl-one,wl-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workload_query", "List of keywords for filtering workloads. Workloads whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pods", "List of pods the query will perform against, eg. pod-one,pod-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pod_query", "List of keywords for filtering pods. Pods whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("containers", "List of containers the query will perform against, eg. container-one,container-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("container_query", "List of keywords for filtering containers. Containers whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/workspaces/{workspace}").To(logging.LoggingQueryWorkspace).
 		Filter(filter.Logging).
-		Doc("workspace level log query").
-		Param(ws.PathParameter("workspace", "workspace specify").DataType("string").Required(true)).
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("namespaces", "namespaces specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("namespace_query", "namespace query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workloads", "workloads specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workload_query", "workload query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pods", "pods specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pod_query", "pod query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("containers", "containers specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("container_query", "container query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against a specific workspace.").
+		Param(ws.PathParameter("workspace", "Perform query against a specific workspace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("namespaces", "List of namespaces the query will perform against, eg. ns-one,ns-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("namespace_query", "List of keywords for filtering namespaces. Namespaces whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workloads", "List of workloads the query will perform against, eg. wl-one,wl-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workload_query", "List of keywords for filtering workloads. Workloads whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pods", "List of pods the query will perform against, eg. pod-one,pod-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pod_query", "List of keywords for filtering pods. Pods whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("containers", "List of containers the query will perform against, eg. container-one,container-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("container_query", "List of keywords for filtering containers. Containers whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}").To(logging.LoggingQueryNamespace).
 		Filter(filter.Logging).
-		Doc("namespace level log query").
-		Param(ws.PathParameter("namespace", "namespace specify").DataType("string").Required(true)).
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("workloads", "workloads specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("workload_query", "workload query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pods", "pods specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pod_query", "pod query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("containers", "containers specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("container_query", "container query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against a specific namespace.").
+		Param(ws.PathParameter("namespace", "Perform query against a specific namespace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("workloads", "List of workloads the query will perform against, eg. wl-one,wl-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("workload_query", "List of keywords for filtering workloads. Workloads whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pods", "List of pods the query will perform against, eg. pod-one,pod-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pod_query", "List of keywords for filtering pods. Pods whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("containers", "List of containers the query will perform against, eg. container-one,container-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("container_query", "List of keywords for filtering containers. Containers whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/workloads/{workload}").To(logging.LoggingQueryWorkload).
 		Filter(filter.Logging).
-		Doc("workload level log query").
-		Param(ws.PathParameter("namespace", "namespace specify").DataType("string").Required(true)).
-		Param(ws.PathParameter("workload", "workload specify").DataType("string").Required(true)).
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("pods", "pods specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("pod_query", "pod query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("containers", "containers specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("container_query", "container query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against a specific workload.").
+		Param(ws.PathParameter("namespace", "Specify the namespace of the workload.").DataType("string").Required(true)).
+		Param(ws.PathParameter("workload", "Perform query against a specific workload.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("pods", "List of pods the query will perform against, eg. pod-one,pod-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("pod_query", "List of keywords for filtering pods. Pods whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("containers", "List of containers the query will perform against, eg. container-one,container-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("container_query", "List of keywords for filtering containers. Containers whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods/{pod}").To(logging.LoggingQueryPod).
 		Filter(filter.Logging).
-		Doc("pod level log query").
-		Param(ws.PathParameter("namespace", "namespace specify").DataType("string").Required(true)).
-		Param(ws.PathParameter("pod", "pod specify").DataType("string").Required(true)).
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("containers", "containers specify").DataType("string").Required(false)).
-		Param(ws.QueryParameter("container_query", "container query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against a specific pod.").
+		Param(ws.PathParameter("namespace", "Specify the namespace of the pod.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Perform query against a specific pod.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("containers", "List of containers the query will perform against, eg. container-one,container-two").DataType("string").Required(false)).
+		Param(ws.QueryParameter("container_query", "List of keywords for filtering containers. Containers whose name contains at least one keyword will be matched for query. Non case-sensitive matching. eg. one,two.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods/{pod}/containers/{container}").To(logging.LoggingQueryContainer).
 		Filter(filter.Logging).
-		Doc("container level log query").
-		Param(ws.PathParameter("namespace", "namespace specify").DataType("string").Required(true)).
-		Param(ws.PathParameter("pod", "pod specify").DataType("string").Required(true)).
-		Param(ws.PathParameter("container", "container specify").DataType("string").Required(true)).
-		Param(ws.QueryParameter("operation", "operation: query statistics").DataType("string").Required(true)).
-		Param(ws.QueryParameter("log_query", "log query keywords").DataType("string").Required(false)).
-		Param(ws.QueryParameter("interval", "interval of time histogram").DataType("string").Required(false)).
-		Param(ws.QueryParameter("start_time", "range start time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("end_time", "range end time").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort", "sort method").DataType("string").Required(false)).
-		Param(ws.QueryParameter("from", "begin index of result returned").DataType("int").Required(true)).
-		Param(ws.QueryParameter("size", "size of result returned").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Log query against a specific container.").
+		Param(ws.PathParameter("namespace", "Specify the namespace of the pod.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the pod of the container.").DataType("string").Required(true)).
+		Param(ws.PathParameter("container", "Perform query against a specific container.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("operation", "Query operation type. One of query, statistics, histogram.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("log_query", "List of keywords  for filtering logs. The query returns log containing at least one keyword. Non case-sensitive matching. eg. err,INFO.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("interval", "Count logs at intervals. Valid only if operation is histogram. The unit can be ms(milliseconds), s(seconds), m(minutes), h(hours), d(days), w(weeks), M(months), q(quarters), y(years). eg. 30m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start_time", "Start time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end_time", "End time of query range, eg. 1559664000000.").DataType("string").Required(false)).
+		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("int").DefaultValue("0").Required(false)).
+		Param(ws.QueryParameter("size", "Size of result to return.").DataType("int").DefaultValue("10").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(esclient.Response{}).
+		Returns(http.StatusOK, RespOK, esclient.Response{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/fluentbit/filters").To(logging.LoggingQueryFluentbitFilters).
 		Filter(filter.Logging).
-		Doc("log fluent-bit filters query").
+		Doc("List all Fluent bit filter plugins. This API is work-in-process.").
 		Metadata(restfulspec.KeyOpenAPITags, tags)).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.POST("/fluentbit/filters").To(logging.LoggingUpdateFluentbitFilters).
 		Filter(filter.Logging).
-		Doc("log fluent-bit filters update").
+		Doc("Add a new Fluent bit filter plugin. This API is work-in-process.").
 		Metadata(restfulspec.KeyOpenAPITags, tags)).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/fluentbit/outputs").To(logging.LoggingQueryFluentbitOutputs).
 		Filter(filter.Logging).
-		Doc("log fluent-bit outputs query").
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("List all Fluent bit output plugins.").
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(log.FluentbitOutputsResult{}).
+		Returns(http.StatusOK, RespOK, log.FluentbitOutputsResult{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.POST("/fluentbit/outputs").To(logging.LoggingInsertFluentbitOutput).
 		Filter(filter.Logging).
-		Doc("log fluent-bit outputs insert").
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Add a new Fluent bit output plugin.").
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Reads(fluentbitclient.OutputPlugin{}).
+		Writes(log.FluentbitOutputsResult{}).
+		Returns(http.StatusOK, RespOK, log.FluentbitOutputsResult{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.POST("/fluentbit/outputs/{output}").To(logging.LoggingUpdateFluentbitOutput).
 		Filter(filter.Logging).
-		Doc("log fluent-bit outputs update").
-		Param(ws.PathParameter("output", "output id").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Update a Fluent bit output plugin.").
+		Param(ws.PathParameter("output", "ID of the output to update.").DataType("string").Required(true)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Reads(fluentbitclient.OutputPlugin{}).
+		Writes(log.FluentbitOutputsResult{}).
+		Returns(http.StatusOK, RespOK, log.FluentbitOutputsResult{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.DELETE("/fluentbit/outputs/{output}").To(logging.LoggingDeleteFluentbitOutput).
 		Filter(filter.Logging).
-		Doc("log fluent-bit outputs delete").
-		Param(ws.PathParameter("output", "output id").DataType("int").Required(true)).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Delete a Fluent bit output plugin.").
+		Param(ws.PathParameter("output", "ID of the output to delete.").DataType("string").Required(true)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(log.FluentbitOutputsResult{}).
+		Returns(http.StatusOK, RespOK, log.FluentbitOutputsResult{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 

pkg/apis/monitoring/v1alpha2/register.go

@@ -23,9 +23,14 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"kubesphere.io/kubesphere/pkg/apiserver/monitoring"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
+	"kubesphere.io/kubesphere/pkg/models/metrics"
+	"net/http"
 )
 
-const GroupName = "monitoring.kubesphere.io"
+const (
+	GroupName = "monitoring.kubesphere.io"
+	RespOK    = "ok"
+)
 
 var GroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha2"}
 
@@ -40,217 +45,280 @@ func addWebService(c *restful.Container) error {
 	tags := []string{"Monitoring"}
 
 	ws.Route(ws.GET("/cluster").To(monitoring.MonitorCluster).
-		Doc("monitor cluster level metrics").
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("cluster_cpu_utilisation")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get cluster-level metrics.").
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. cluster_cpu|cluster_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/nodes").To(monitoring.MonitorNode).
-		Doc("monitor nodes level metrics").
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("node_cpu_utilisation")).
-		Param(ws.QueryParameter("resources_filter", "node re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get node-level metrics.").
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. node_cpu|node_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Node filter in regexp pattern, eg. i-caojnter|i-cmu82ogj.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort nodes by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/nodes/{node}").To(monitoring.MonitorNode).
-		Doc("monitor specific node level metrics").
-		Param(ws.PathParameter("node", "specific node").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("node_cpu_utilisation")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific node metrics.").
+		Param(ws.PathParameter("node", "Specify the target node.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. node_cpu|node_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces").To(monitoring.MonitorNamespace).
-		Doc("monitor namespaces level metrics").
-		Param(ws.QueryParameter("resources_filter", "namespaces re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("namespace_memory_utilisation")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get namespace-level metrics.").
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. namespace_cpu|namespace_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Namespace filter in regexp pattern, eg. namespace-1|namespace-2.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort namespaces by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}").To(monitoring.MonitorNamespace).
-		Doc("monitor specific namespace level metrics").
-		Param(ws.PathParameter("namespace", "specific namespace").DataType("string").Required(true).DefaultValue("monitoring")).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("namespace_memory_utilisation")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific namespace metrics.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. namespace_cpu|namespace_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods").To(monitoring.MonitorPod).
-		Doc("monitor pods level metrics").
-		Param(ws.PathParameter("namespace", "specific namespace").DataType("string").Required(true).DefaultValue("monitoring")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("pod_memory_utilisation_wo_cache")).
-		Param(ws.QueryParameter("resources_filter", "pod re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get pod-level metrics of a given namespace.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. pod_cpu|pod_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Pods filter in regexp pattern, eg. coredns-77b8449dc9-hd6gd|coredns-77b8449dc9-b4n74.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort pods by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods/{pod}").To(monitoring.MonitorPod).
-		Doc("monitor specific pod level metrics").
-		Param(ws.PathParameter("namespace", "specific namespace").DataType("string").Required(true).DefaultValue("monitoring")).
-		Param(ws.PathParameter("pod", "specific pod").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("pod_memory_utilisation_wo_cache")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific pod metrics.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the target pod.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. pod_cpu|pod_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/nodes/{node}/pods").To(monitoring.MonitorPod).
-		Doc("monitor pods level metrics by nodeid").
-		Param(ws.PathParameter("node", "specific node").DataType("string").Required(true).DefaultValue("i-k89a62il")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("pod_memory_utilisation_wo_cache")).
-		Param(ws.QueryParameter("resources_filter", "pod re2 expression filter").DataType("string").Required(false).DefaultValue("openpitrix.*")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get metrics of all pod on a specific node.").
+		Param(ws.PathParameter("node", "Specify the target node.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. node_cpu|node_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Pod filter in regexp pattern, eg. coredns-77b8449dc9-hd6gd|coredns-77b8449dc9-b4n74.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort pods by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/nodes/{node}/pods/{pod}").To(monitoring.MonitorPod).
-		Doc("monitor specific pod level metrics by nodeid").
-		Param(ws.PathParameter("node", "specific node").DataType("string").Required(true).DefaultValue("i-k89a62il")).
-		Param(ws.PathParameter("pod", "specific pod").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("pod_memory_utilisation_wo_cache")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific pod metrics under a given namespace.").
+		Param(ws.PathParameter("node", "Specify the target node.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the target pod.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. pod_cpu|pod_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/nodes/{node}/pods/{pod}/containers").To(monitoring.MonitorContainer).
-		Doc("monitor specific pod level metrics by nodeid").
-		Param(ws.PathParameter("node", "specific node").DataType("string").Required(true)).
-		Param(ws.PathParameter("pod", "specific pod").DataType("string").Required(true)).
-		Param(ws.QueryParameter("resources_filter", "container re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...").DataType("string").Required(false)).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("pod_memory_utilisation_wo_cache")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get container-level metrics under a given node and pod.").
+		Param(ws.PathParameter("node", "Specify the target node.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the target pod.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. container_cpu|container_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Container filter in regexp pattern.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort containers by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods/{pod}/containers").To(monitoring.MonitorContainer).
-		Doc("monitor containers level metrics").
-		Param(ws.PathParameter("namespace", "specific namespace").DataType("string").Required(true).DefaultValue("monitoring")).
-		Param(ws.PathParameter("pod", "specific pod").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("resources_filter", "container re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...").DataType("string").Required(false)).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("container_memory_utilisation_wo_cache")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get container-level metrics under a given namespace and pod.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the target pod.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. container_cpu|container_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Container filter in regexp pattern.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort containers by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/pods/{pod}/containers/{container}").To(monitoring.MonitorContainer).
-		Doc("monitor specific container level metrics").
-		Param(ws.PathParameter("namespace", "specific namespace").DataType("string").Required(true).DefaultValue("monitoring")).
-		Param(ws.PathParameter("pod", "specific pod").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.PathParameter("container", "specific container").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_name", "metrics name cpu memory...").DataType("string").Required(true).DefaultValue("container_memory_utilisation_wo_cache")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific container metrics under a given node and pod.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.PathParameter("pod", "Specify the target pod.").DataType("string").Required(true)).
+		Param(ws.PathParameter("container", "Specify the target container.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. container_cpu|container_memory.").DataType("string").Required(false)).Metadata(restfulspec.KeyOpenAPITags, tags).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	// Only use this api to monitor status of pods under the {workload}
 	// To monitor a specific workload, try the next two apis with "resources_filter"
 	ws.Route(ws.GET("/namespaces/{namespace}/workloads/{workload_kind}/{workload}").To(monitoring.MonitorWorkload).
-		Doc("monitor specific workload level metrics").
-		Param(ws.PathParameter("namespace", "namespace").DataType("string").Required(true).DefaultValue("kube-system")).
-		Param(ws.PathParameter("workload_kind", "workload kind").DataType("string").Required(true).DefaultValue("daemonset")).
-		Param(ws.PathParameter("workload", "workload name").DataType("string").Required(true).DefaultValue("")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...").DataType("string").Required(false)).
-		Param(ws.QueryParameter("resources_filter", "pod re2 expression filter").DataType("string").Required(false).DefaultValue("openpitrix.*")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "max metric items in a page").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific workload metrics under a given namespace.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.PathParameter("workload_kind", "Specify the target workload kind. One of deployment, daemonset, statefulset. Other values will be interpreted as any of three.").DataType("string").Required(true).DefaultValue("(.*)")).
+		Param(ws.PathParameter("workload", "Specify the target workload.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. workload_cpu|workload_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/workloads/{workload_kind}").To(monitoring.MonitorWorkload).
-		Doc("monitor specific workload kind level metrics").
-		Param(ws.PathParameter("namespace", "namespace").DataType("string").Required(true).DefaultValue("kube-system")).
-		Param(ws.PathParameter("workload_kind", "workload kind").DataType("string").Required(true).DefaultValue("daemonset")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...").DataType("string").Required(false)).
-		Param(ws.QueryParameter("resources_filter", "pod re2 expression filter").DataType("string").Required(false).DefaultValue("openpitrix.*")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "max metric items in a page").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get workload-level metrics of specific workload kind.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.PathParameter("workload_kind", "Specify the target workload kind. One of deployment, daemonset, statefulset. Other values will be interpreted as any of three.").DataType("string").Required(true).DefaultValue("(.*)")).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. node_cpu|node_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Workload filter in regexp pattern.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort workloads by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/namespaces/{namespace}/workloads").To(monitoring.MonitorWorkload).
-		Doc("monitor all workload level metrics").
-		Param(ws.PathParameter("namespace", "namespace").DataType("string").Required(true).DefaultValue("kube-system")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...").DataType("string").Required(false)).
-		Param(ws.QueryParameter("resources_filter", "pod re2 expression filter").DataType("string").Required(false).DefaultValue("")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get workload-level metrics under a given namespace.").
+		Param(ws.PathParameter("namespace", "Specify the target namespace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. workload_cpu|workload_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Workload filter in regexp pattern.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort workloads by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	// list all namespace in this workspace by selected metrics
 	ws.Route(ws.GET("/workspaces/{workspace}").To(monitoring.MonitorOneWorkspace).
-		Doc("monitor workspaces level metrics").
-		Param(ws.PathParameter("workspace", "workspace name").DataType("string").Required(true)).
-		Param(ws.QueryParameter("resources_filter", "namespaces filter").DataType("string").Required(false).DefaultValue("k.*")).
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("namespace_memory_utilisation_wo_cache")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get specific workspace metrics.").
+		Param(ws.PathParameter("workspace", "Specify the target workspace.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. workspace_cpu|workspace_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/workspaces").To(monitoring.MonitorAllWorkspaces).
-		Doc("monitor workspaces level metrics").
-		Param(ws.QueryParameter("metrics_filter", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("workspace_memory_utilisation")).
-		Param(ws.QueryParameter("resources_filter", "workspaces re2 expression filter").DataType("string").Required(false).DefaultValue(".*")).
-		Param(ws.QueryParameter("sort_metric", "sort metric").DataType("string").Required(false)).
-		Param(ws.QueryParameter("sort_type", "ascending descending order").DataType("string").Required(false)).
-		Param(ws.QueryParameter("page", "page number").DataType("string").Required(false).DefaultValue("1")).
-		Param(ws.QueryParameter("limit", "metrics name cpu memory...in re2 regex").DataType("string").Required(false).DefaultValue("4")).
-		Param(ws.QueryParameter("type", "rank, statistic").DataType("string").Required(false).DefaultValue("rank")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get workspace-level metrics.").
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. workspace_cpu|workspace_memory.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("resources_filter", "Workspace filter in regexp pattern, eg. workspace_1|workspace_2.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_metric", "Sort workspaces by the specified metric. Valid only if type is rank.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("sort_type", "Sorting order, one of asc, desc. Valid only if type is rank.").DefaultValue("desc.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("page", "The number of paged results per metric. Default to return the whole metrics.").DataType("int").Required(false).DefaultValue("1")).
+		Param(ws.QueryParameter("limit", "Max count of items per page.").DataType("int").Required(false).DefaultValue("5")).
+		Param(ws.QueryParameter("type", "Additional operation to the result. One of rank, statistic.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 
 	ws.Route(ws.GET("/components/{component}").To(monitoring.MonitorComponent).
-		Doc("monitor component level metrics").
-		Param(ws.QueryParameter("metrics_filter", "metrics names in re2 regex").DataType("string").Required(false).DefaultValue("")).
-		Metadata(restfulspec.KeyOpenAPITags, tags)).
+		Doc("Get service component-level metrics.").
+		Param(ws.PathParameter("component", "Specify the target component. One of etcd, apiserver, scheduler, controller_manager, coredns, prometheus.").DataType("string").Required(true)).
+		Param(ws.QueryParameter("metrics_filter", "Metrics filter in regexp pattern, eg. etcd_server_list|coredns_proxy.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("step", "Used to get metrics over a range of time. Query resolution step. eg. 10m.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("start", "Used to get metrics over a range of time. Start time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("end", "Used to get metrics over a range of time. End time of query range. eg. 1559762729.").DataType("string").Required(false)).
+		Param(ws.QueryParameter("time", "Used to get metrics at a given time point. eg. 1559762729.").DataType("string").Required(false)).
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Writes(metrics.FormatedLevelMetric{}).
+		Returns(http.StatusOK, RespOK, metrics.FormatedLevelMetric{})).
 		Consumes(restful.MIME_JSON, restful.MIME_XML).
 		Produces(restful.MIME_JSON)
 

pkg/apis/operations/v1alpha2/register.go

@@ -24,6 +24,7 @@ import (
 	"kubesphere.io/kubesphere/pkg/apiserver/operations"
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/errors"
+	"net/http"
 )
 
 const GroupName = "operations.kubesphere.io"
@@ -38,24 +39,24 @@ 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("").
+		Doc("Drain node").
 		Param(webservice.PathParameter("node", "node name")).
-		Writes(errors.Error{}))
+		Returns(http.StatusOK, ok, errors.Error{}))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/jobs/{job}").
 		To(operations.RerunJob).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Doc("Handle job operation").
+		Doc("Job rerun").
 		Param(webservice.PathParameter("job", "job name")).
 		Param(webservice.PathParameter("namespace", "job's namespace")).
 		Param(webservice.QueryParameter("a", "action")).
-		Writes(""))
+		Returns(http.StatusOK, ok, errors.Error{}))
 
 	c.Add(webservice)
 

pkg/apis/resources/v1alpha2/register.go

@@ -36,8 +36,11 @@ import (
 	"kubesphere.io/kubesphere/pkg/models"
 	"kubesphere.io/kubesphere/pkg/models/applications"
 	gitmodel "kubesphere.io/kubesphere/pkg/models/git"
+	registriesmodel "kubesphere.io/kubesphere/pkg/models/registries"
+	"kubesphere.io/kubesphere/pkg/models/status"
 	"kubesphere.io/kubesphere/pkg/params"
 	"kubesphere.io/kubesphere/pkg/simple/client/openpitrix"
+	"net/http"
 )
 
 const GroupName = "resources.kubesphere.io"
@@ -54,6 +57,7 @@ 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.ListResources).
@@ -68,13 +72,13 @@ func addWebService(c *restful.Container) error {
 			Required(false).
 			DataFormat("limit=%d,page=%d").
 			DefaultValue("limit=10,page=1")).
-		Writes(models.PageableResponse{}))
+		Returns(http.StatusOK, ok, models.PageableResponse{}))
 
 	tags = []string{"Cluster resources"}
 
 	webservice.Route(webservice.GET("/{resources}").
 		To(resources.ListResources).
-		Writes(models.PageableResponse{}).
+		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Cluster level resource query").
 		Param(webservice.PathParameter("resources", "cluster level resource type"))).
@@ -91,7 +95,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/applications").
 		To(resources.ListApplication).
-		Writes(models.PageableResponse{}).
+		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("List applications in cluster").
 		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
@@ -107,7 +111,7 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/applications").
 		To(resources.ListNamespacedApplication).
-		Writes(models.PageableResponse{}).
+		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("List applications").
 		Param(webservice.QueryParameter(params.ConditionsParam, "query conditions").
@@ -122,24 +126,27 @@ func addWebService(c *restful.Container) error {
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/applications/{cluster_id}").
 		To(resources.DescribeApplication).
-		Writes(applications.Application{}).
+		Returns(http.StatusOK, ok, applications.Application{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Describe application").
 		Param(webservice.PathParameter("namespace", "namespace name")).
-		Param(webservice.PathParameter("cluster_id", "openpitrix cluster id")))
+		Param(webservice.PathParameter("cluster_id", "application id")))
 
 	webservice.Route(webservice.POST("/namespaces/{namespace}/applications").
 		To(resources.DeployApplication).
 		Doc("Deploy application").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Reads(openpitrix.CreateClusterRequest{}).
+		Returns(http.StatusOK, ok, errors.Error{}).
 		Param(webservice.PathParameter("namespace", "namespace name")))
 
 	webservice.Route(webservice.DELETE("/namespaces/{namespace}/applications/{cluster_id}").
 		To(resources.DeleteApplication).
 		Doc("Delete application").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Param(webservice.PathParameter("namespace", "namespace name")))
+		Returns(http.StatusOK, ok, errors.Error{}).
+		Param(webservice.PathParameter("namespace", "namespace name")).
+		Param(webservice.PathParameter("cluster_id", "application id")))
 
 	tags = []string{"User resources"}
 
@@ -148,13 +155,14 @@ func addWebService(c *restful.Container) error {
 		Doc("get user's kubectl pod").
 		Param(webservice.PathParameter("username", "username")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Writes(models.PodInfo{}))
+		Returns(http.StatusOK, ok, models.PodInfo{}))
 
 	webservice.Route(webservice.GET("/users/{username}/kubeconfig").
 		Produces("text/plain").
 		To(resources.GetKubeconfig).
 		Doc("get users' kubeconfig").
 		Param(webservice.PathParameter("username", "username")).
+		Returns(http.StatusOK, ok, "").
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 
 	tags = []string{"Components"}
@@ -163,18 +171,18 @@ func addWebService(c *restful.Container) error {
 		To(components.GetComponents).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("").
-		Writes(map[string]models.Component{}))
+		Returns(http.StatusOK, ok, map[string]models.Component{}))
 	webservice.Route(webservice.GET("/components/{component}").
 		To(components.GetComponentStatus).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("").
 		Param(webservice.PathParameter("component", "component name")).
-		Writes(models.Component{}))
+		Returns(http.StatusOK, ok, models.Component{}))
 	webservice.Route(webservice.GET("/health").
 		To(components.GetSystemHealthStatus).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("").
-		Writes(map[string]int{}))
+		Returns(http.StatusOK, ok, map[string]int{}))
 
 	tags = []string{"Quotas"}
 
@@ -182,13 +190,13 @@ func addWebService(c *restful.Container) error {
 		To(quotas.GetClusterQuotas).
 		Deprecate().
 		Doc("get whole cluster's resource usage").
-		Writes(models.ResourceQuota{}).
+		Returns(http.StatusOK, ok, models.ResourceQuota{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/quotas").
 		Doc("get specified namespace's resource quota and usage").
 		Param(webservice.PathParameter("namespace", "namespace's name")).
-		Writes(models.ResourceQuota{}).
+		Returns(http.StatusOK, ok, models.ResourceQuota{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		To(quotas.GetNamespaceQuotas))
 
@@ -198,7 +206,8 @@ func addWebService(c *restful.Container) error {
 		To(registries.RegistryVerify).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("docker registry verify").
-		Writes(errors.Error{}))
+		Reads(registriesmodel.AuthInfo{}).
+		Returns(http.StatusOK, ok, errors.Error{}))
 
 	tags = []string{"Git"}
 	webservice.Route(webservice.POST("/git/readverify").
@@ -207,7 +216,7 @@ func addWebService(c *restful.Container) error {
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("secret git read verify").
 		Reads(gitmodel.AuthInfo{}).
-		Writes(errors.Error{}),
+		Returns(http.StatusOK, ok, errors.Error{}),
 	)
 	tags = []string{"Revision"}
 
@@ -218,7 +227,7 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("daemonset", "daemonset's name")).
 		Param(webservice.PathParameter("namespace", "daemonset's namespace")).
 		Param(webservice.PathParameter("revision", "daemonset's revision")).
-		Writes(appsv1.DaemonSet{}))
+		Returns(http.StatusOK, ok, appsv1.DaemonSet{}))
 	webservice.Route(webservice.GET("/namespaces/{namespace}/deployments/{deployment}/revisions/{revision}").
 		To(revisions.GetDeployRevision).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
@@ -226,7 +235,7 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("deployment", "deployment's name")).
 		Param(webservice.PathParameter("namespace", "deployment's namespace")).
 		Param(webservice.PathParameter("revision", "deployment's revision")).
-		Writes(appsv1.ReplicaSet{}))
+		Returns(http.StatusOK, ok, appsv1.ReplicaSet{}))
 	webservice.Route(webservice.GET("/namespaces/{namespace}/statefulsets/{statefulset}/revisions/{revision}").
 		To(revisions.GetStatefulSetRevision).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
@@ -234,7 +243,7 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("statefulset", "statefulset's name")).
 		Param(webservice.PathParameter("namespace", "statefulset's namespace")).
 		Param(webservice.PathParameter("revision", "statefulset's revision")).
-		Writes(appsv1.StatefulSet{}))
+		Returns(http.StatusOK, ok, appsv1.StatefulSet{}))
 
 	tags = []string{"Router"}
 
@@ -242,7 +251,7 @@ func addWebService(c *restful.Container) error {
 		To(routers.GetAllRouters).
 		Doc("List all routers").
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Writes(corev1.Service{}))
+		Returns(http.StatusOK, ok, corev1.Service{}))
 
 	webservice.Route(webservice.GET("/namespaces/{namespace}/router").
 		To(routers.GetRouter).
@@ -273,11 +282,13 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.GET("/workloadstatuses").
 		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").
 		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))
 
 	c.Add(webservice)

pkg/apis/servicemesh/metrics/v1alpha2/register.go

@@ -7,7 +7,7 @@ import (
 	"kubesphere.io/kubesphere/pkg/apiserver/runtime"
 	"kubesphere.io/kubesphere/pkg/apiserver/servicemesh/metrics"
 	"kubesphere.io/kubesphere/pkg/apiserver/servicemesh/tracing"
-	"kubesphere.io/kubesphere/pkg/errors"
+	"net/http"
 )
 
 const GroupName = "servicemesh.kubesphere.io"
@@ -30,19 +30,21 @@ func addWebService(c *restful.Container) error {
 	webservice.Route(webservice.GET("/namespaces/{namespace}/services/{service}/metrics").
 		To(metrics.GetServiceMetrics).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Doc("Get app metrics from a specific namespace").
+		Doc("Get service metrics from a specific namespace").
 		Param(webservice.PathParameter("namespace", "name of the namespace")).
 		Param(webservice.PathParameter("service", "name of the service")).
-		Param(webservice.QueryParameter("filters[]", "type of metrics type, e.g. request_count, request_duration, request_error_count")).
+		Param(webservice.QueryParameter("filters[]", "type of metrics type, fetch all metrics when empty, e.g. request_count, request_duration, request_error_count").DefaultValue("[]")).
 		Param(webservice.QueryParameter("queryTime", "from which UNIX time to extract metrics")).
-		Param(webservice.QueryParameter("duration", "metrics duration, in seconds")).
-		Param(webservice.QueryParameter("step", "metrics step")).
-		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s")).
-		Param(webservice.QueryParameter("quantiles[]", "metrics quantiles, 0.5, 0.9, 0.99")).
-		Param(webservice.QueryParameter("byLabels[]", "by which labels to group node, e.g. source_workload, destination_service_name")).
-		Param(webservice.QueryParameter("requestProtocol", "request protocol, http/tcp")).
-		Param(webservice.QueryParameter("reporter", "destination")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("1800")).
+		Param(webservice.QueryParameter("step", "step between graph data points, in seconds.").DefaultValue("15")).
+		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s").DefaultValue("1m")).
+		Param(webservice.QueryParameter("direction", "traffic direction: 'inbound' or 'outbound'").DefaultValue("outbound")).
+		Param(webservice.QueryParameter("quantiles[]", "list of quantiles to fetch, fetch no quantiles when empty. eg. 0.5, 0.9, 0.99").DefaultValue("[]")).
+		Param(webservice.QueryParameter("byLabels[]", "list of labels to use for grouping metrics(via Prometheus 'by' clause), e.g. source_workload, destination_service_name").DefaultValue("[]")).
+		Param(webservice.QueryParameter("requestProtocol", "request protocol for the telemetry, e.g. http/tcp/grpc").DefaultValue("all protocols")).
+		Param(webservice.QueryParameter("reporter", "istio telemetry reporter, 'source' or 'destination'").DefaultValue("source")).
+		Returns(http.StatusOK, "ok", MetricsResponse{}).
+		Writes(MetricsResponse{})).Produces(restful.MIME_JSON)
 
 	// Get app metrics
 	// Get /namespaces/{namespace}/apps/{app}/metrics
@@ -51,17 +53,20 @@ func addWebService(c *restful.Container) error {
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Get app metrics from a specific namespace").
 		Param(webservice.PathParameter("namespace", "name of the namespace")).
-		Param(webservice.PathParameter("app", "name of the workload label app value")).
-		Param(webservice.QueryParameter("filters[]", "type of metrics type, e.g. request_count, request_duration, request_error_count")).
+		Param(webservice.PathParameter("app", "name of the app")).
+		Param(webservice.QueryParameter("filters[]", "type of metrics type, fetch all metrics when empty, e.g. request_count, request_duration, request_error_count").DefaultValue("[]")).
 		Param(webservice.QueryParameter("queryTime", "from which UNIX time to extract metrics")).
-		Param(webservice.QueryParameter("duration", "metrics duration, in seconds")).
-		Param(webservice.QueryParameter("step", "metrics step")).
-		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s")).
-		Param(webservice.QueryParameter("quantiles[]", "metrics quantiles, 0.5, 0.9, 0.99")).
-		Param(webservice.QueryParameter("byLabels[]", "by which labels to group node, e.g. source_workload, destination_service_name")).
-		Param(webservice.QueryParameter("requestProtocol", "request protocol, http/tcp")).
-		Param(webservice.QueryParameter("reporter", "destination")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("1800")).
+		Param(webservice.QueryParameter("step", "step between graph data points, in seconds.").DefaultValue("15")).
+		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s").DefaultValue("1m")).
+		Param(webservice.QueryParameter("direction", "traffic direction: 'inbound' or 'outbound'").DefaultValue("outbound")).
+		Param(webservice.QueryParameter("quantiles[]", "list of quantiles to fetch, fetch no quantiles when empty. eg. 0.5, 0.9, 0.99").DefaultValue("[]")).
+		Param(webservice.QueryParameter("byLabels[]", "list of labels to use for grouping metrics(via Prometheus 'by' clause), e.g. source_workload, destination_service_name").DefaultValue("[]")).
+		Param(webservice.QueryParameter("requestProtocol", "request protocol for the telemetry, e.g. http/tcp/grpc").DefaultValue("all protocols")).
+		Param(webservice.QueryParameter("reporter", "istio telemetry reporter, 'source' or 'destination'").DefaultValue("source")).
+		Returns(http.StatusOK, "ok", MetricsResponse{}).
+		Writes(MetricsResponse{})).
+		Produces(restful.MIME_JSON)
 
 	// Get workload metrics
 	// Get /namespaces/{namespace}/workloads/{workload}/metrics
@@ -71,16 +76,20 @@ func addWebService(c *restful.Container) error {
 		Doc("Get workload metrics from a specific namespace").
 		Param(webservice.PathParameter("namespace", "name of the namespace").Required(true)).
 		Param(webservice.PathParameter("workload", "name of the workload").Required(true)).
-		Param(webservice.QueryParameter("filters[]", "type of metrics type, e.g. request_count, request_duration, request_error_count")).
+		Param(webservice.PathParameter("service", "name of the service")).
+		Param(webservice.QueryParameter("filters[]", "type of metrics type, fetch all metrics when empty, e.g. request_count, request_duration, request_error_count").DefaultValue("[]")).
 		Param(webservice.QueryParameter("queryTime", "from which UNIX time to extract metrics")).
-		Param(webservice.QueryParameter("duration", "metrics duration, in seconds")).
-		Param(webservice.QueryParameter("step", "metrics step")).
-		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s")).
-		Param(webservice.QueryParameter("quantiles[]", "metrics quantiles, 0.5, 0.9, 0.99")).
-		Param(webservice.QueryParameter("byLabels[]", "by which labels to group node, e.g. source_workload, destination_service_name")).
-		Param(webservice.QueryParameter("requestProtocol", "request protocol, http/tcp")).
-		Param(webservice.QueryParameter("reporter", "destination")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("1800")).
+		Param(webservice.QueryParameter("step", "step between graph data points, in seconds.").DefaultValue("15")).
+		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s").DefaultValue("1m")).
+		Param(webservice.QueryParameter("direction", "traffic direction: 'inbound' or 'outbound'").DefaultValue("outbound")).
+		Param(webservice.QueryParameter("quantiles[]", "list of quantiles to fetch, fetch no quantiles when empty. eg. 0.5, 0.9, 0.99").DefaultValue("[]")).
+		Param(webservice.QueryParameter("byLabels[]", "list of labels to use for grouping metrics(via Prometheus 'by' clause), e.g. source_workload, destination_service_name").DefaultValue("[]")).
+		Param(webservice.QueryParameter("requestProtocol", "request protocol for the telemetry, e.g. http/tcp/grpc").DefaultValue("all protocols")).
+		Param(webservice.QueryParameter("reporter", "istio telemetry reporter, 'source' or 'destination'").DefaultValue("source")).
+		Returns(http.StatusOK, "ok", MetricsResponse{}).
+		Writes(MetricsResponse{})).
+		Produces(restful.MIME_JSON)
 
 	// Get namespace metrics
 	// Get /namespaces/{namespace}/metrics
@@ -89,16 +98,19 @@ func addWebService(c *restful.Container) error {
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Get workload metrics from a specific namespace").
 		Param(webservice.PathParameter("namespace", "name of the namespace").Required(true)).
-		Param(webservice.QueryParameter("filters[]", "type of metrics type, e.g. request_count, request_duration, request_error_count")).
+		Param(webservice.PathParameter("service", "name of the service")).
+		Param(webservice.QueryParameter("filters[]", "type of metrics type, fetch all metrics when empty, e.g. request_count, request_duration, request_error_count").DefaultValue("[]")).
 		Param(webservice.QueryParameter("queryTime", "from which UNIX time to extract metrics")).
-		Param(webservice.QueryParameter("duration", "metrics duration, in seconds")).
-		Param(webservice.QueryParameter("step", "metrics step")).
-		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s")).
-		Param(webservice.QueryParameter("quantiles[]", "metrics quantiles, 0.5, 0.9, 0.99")).
-		Param(webservice.QueryParameter("byLabels[]", "by which labels to group node, e.g. source_workload, destination_service_name")).
-		Param(webservice.QueryParameter("requestProtocol", "request protocol, http/tcp")).
-		Param(webservice.QueryParameter("reporter", "destination")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("1800")).
+		Param(webservice.QueryParameter("step", "step between graph data points, in seconds.").DefaultValue("15")).
+		Param(webservice.QueryParameter("rateInterval", "metrics rate intervals, e.g. 20s").DefaultValue("1m")).
+		Param(webservice.QueryParameter("direction", "traffic direction: 'inbound' or 'outbound'").DefaultValue("outbound")).
+		Param(webservice.QueryParameter("quantiles[]", "list of quantiles to fetch, fetch no quantiles when empty. eg. 0.5, 0.9, 0.99").DefaultValue("[]")).
+		Param(webservice.QueryParameter("byLabels[]", "list of labels to use for grouping metrics(via Prometheus 'by' clause), e.g. source_workload, destination_service_name").DefaultValue("[]")).
+		Param(webservice.QueryParameter("requestProtocol", "request protocol for the telemetry, e.g. http/tcp/grpc").DefaultValue("all protocols")).
+		Param(webservice.QueryParameter("reporter", "istio telemetry reporter, 'source' or 'destination'").DefaultValue("source")).
+		Returns(http.StatusOK, "ok", MetricsResponse{}).
+		Writes(MetricsResponse{})).Produces(restful.MIME_JSON)
 
 	// Get namespace graph
 	// Get /namespaces/{namespace}/graph
@@ -107,25 +119,31 @@ func addWebService(c *restful.Container) error {
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Doc("Get service graph for a specific namespace").
 		Param(webservice.PathParameter("namespace", "name of a namespace").Required(true)).
-		Param(webservice.QueryParameter("graphType", "type of the generated service graph, eg. ")).
-		Param(webservice.QueryParameter("groupBy", "group nodes by kind")).
-		Param(webservice.QueryParameter("queryTime", "from which time point, default now")).
-		Param(webservice.QueryParameter("injectServiceNodes", "whether to inject service ndoes")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("10m")).
+		Param(webservice.QueryParameter("graphType", "type of the generated service graph. Available graph types: [app, service, versionedApp, workload].").DefaultValue("workload")).
+		Param(webservice.QueryParameter("groupBy", "app box grouping characteristic. Available groupings: [app, none, version].").DefaultValue("none")).
+		Param(webservice.QueryParameter("queryTime", "from which time point in UNIX timestamp, default now")).
+		Param(webservice.QueryParameter("injectServiceNodes", "flag for injecting the requested service node between source and destination nodes.").DefaultValue("false")).
+		Returns(http.StatusBadRequest, "bad request", BadRequestError{}).
+		Returns(http.StatusNotFound, "not found", NotFoundError{}).
+		Returns(http.StatusOK, "ok", GraphResponse{}).
+		Writes(GraphResponse{})).Produces(restful.MIME_JSON)
 
 	// Get namespaces graph, for multiple namespaces
 	// Get /namespaces/graph
-	webservice.Route(webservice.GET("/namespaces/{namespace}/graph").
+	webservice.Route(webservice.GET("/namespaces/graph").
 		To(metrics.GetNamespacesGraph).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Doc("Get service graph for a specific namespace").
-		Param(webservice.PathParameter("namespace", "name of a namespace").Required(true)).
-		Param(webservice.QueryParameter("graphType", "type of the generated service graph, eg. ")).
-		Param(webservice.QueryParameter("groupBy", "group nodes by kind")).
-		Param(webservice.QueryParameter("queryTime", "from which time point, default now")).
-		Param(webservice.QueryParameter("injectServiceNodes", "whether to inject service ndoes")).
-		Param(webservice.QueryParameter("namespaces", "names of namespaces")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Doc("Get graph from all namespaces").
+		Param(webservice.QueryParameter("duration", "duration of the query period, in seconds").DefaultValue("10m")).
+		Param(webservice.QueryParameter("graphType", "type of the generated service graph. Available graph types: [app, service, versionedApp, workload].").DefaultValue("workload")).
+		Param(webservice.QueryParameter("groupBy", "app box grouping characteristic. Available groupings: [app, none, version].").DefaultValue("none")).
+		Param(webservice.QueryParameter("queryTime", "from which time point in UNIX timestamp, default now")).
+		Param(webservice.QueryParameter("injectServiceNodes", "flag for injecting the requested service node between source and destination nodes.").DefaultValue("false")).
+		Returns(http.StatusBadRequest, "bad request", BadRequestError{}).
+		Returns(http.StatusNotFound, "not found", NotFoundError{}).
+		Returns(http.StatusOK, "ok", GraphResponse{}).
+		Writes(GraphResponse{})).Produces(restful.MIME_JSON)
 
 	// Get namespace health
 	webservice.Route(webservice.GET("/namespaces/{namespace}/health").
@@ -136,7 +154,10 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("type", "the type of health, app/service/workload, default app").DefaultValue("app")).
 		Param(webservice.QueryParameter("rateInterval", "the rate interval used for fetching error rate").DefaultValue("10m").Required(true)).
 		Param(webservice.QueryParameter("queryTime", "the time to use for query")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Returns(http.StatusBadRequest, "bad request", BadRequestError{}).
+		Returns(http.StatusNotFound, "not found", NotFoundError{}).
+		Returns(http.StatusOK, "ok", namespaceAppHealthResponse{}).
+		Writes(namespaceAppHealthResponse{})).Produces(restful.MIME_JSON)
 
 	// Get workloads health
 	webservice.Route(webservice.GET("/namespaces/{namespace}/workloads/{workload}/health").
@@ -147,7 +168,8 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("workload", "workload name").Required(true)).
 		Param(webservice.QueryParameter("rateInterval", "the rate interval used for fetching error rate").DefaultValue("10m").Required(true)).
 		Param(webservice.QueryParameter("queryTime", "the time to use for query")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		ReturnsError(http.StatusOK, "ok", workloadHealthResponse{}).
+		Writes(workloadHealthResponse{})).Produces(restful.MIME_JSON)
 
 	// Get app health
 	webservice.Route(webservice.GET("/namespaces/{namespace}/apps/{app}/health").
@@ -158,7 +180,8 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("app", "app name").Required(true)).
 		Param(webservice.QueryParameter("rateInterval", "the rate interval used for fetching error rate").DefaultValue("10m").Required(true)).
 		Param(webservice.QueryParameter("queryTime", "the time to use for query")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Returns(http.StatusOK, "ok", appHealthResponse{}).
+		Writes(appHealthResponse{})).Produces(restful.MIME_JSON)
 
 	// Get service health
 	webservice.Route(webservice.GET("/namespaces/{namespace}/services/{service}/health").
@@ -169,7 +192,8 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.PathParameter("service", "service name").Required(true)).
 		Param(webservice.QueryParameter("rateInterval", "the rate interval used for fetching error rate").DefaultValue("10m").Required(true)).
 		Param(webservice.QueryParameter("queryTime", "the time to use for query")).
-		Writes(errors.Error{})).Produces(restful.MIME_JSON)
+		Returns(http.StatusOK, "ok", serviceHealthResponse{}).
+		Writes(serviceHealthResponse{})).Produces(restful.MIME_JSON)
 
 	// Get service tracing
 	webservice.Route(webservice.GET("/namespaces/{namespace}/services/{service}/traces").
@@ -182,9 +206,8 @@ func addWebService(c *restful.Container) error {
 		Param(webservice.QueryParameter("end", "end of time range want to query, in unix timestamp")).
 		Param(webservice.QueryParameter("limit", "maximum tracing entries returned at one query, default 10").DefaultValue("10")).
 		Param(webservice.QueryParameter("loopback", "loopback of duration want to query, e.g. 30m/1h/2d")).
-		Param(webservice.QueryParameter("maxDuration", "maximum duration of tracing")).
-		Param(webservice.QueryParameter("minDuration", "minimum duration of tracing")).
-		Writes(errors.Error{}).
+		Param(webservice.QueryParameter("maxDuration", "maximum duration of a request")).
+		Param(webservice.QueryParameter("minDuration", "minimum duration of a request")).
 		Consumes(restful.MIME_JSON).
 		Produces(restful.MIME_JSON))
 

pkg/apis/servicemesh/metrics/v1alpha2/swagger-doc.go

+package v1alpha2
+
+import (
+	"github.com/kiali/kiali/graph/cytoscape"
+	"github.com/kiali/kiali/models"
+	"github.com/kiali/kiali/prometheus"
+)
+
+/////////////////////
+// SWAGGER RESPONSES
+/////////////////////
+
+// NoContent: the response is empty
+type NoContent struct {
+	Status int32 `json:"status"`
+	Reason error `json:"reason"`
+}
+
+// BadRequestError: the client request is incorrect
+type BadRequestError struct {
+	Status int32 `json:"status"`
+	Reason error `json:"reason"`
+}
+
+// NotFoundError is the error message that is generated when server could not find
+// what was requested
+type NotFoundError struct {
+	Status int32 `json:"status"`
+	Reason error `json:"reason"`
+}
+
+type GraphResponse struct {
+	cytoscape.Config
+}
+
+type serviceHealthResponse struct {
+	models.ServiceHealth
+}
+
+type namespaceAppHealthResponse struct {
+	models.NamespaceAppHealth
+}
+
+type workloadHealthResponse struct {
+	models.WorkloadHealth
+}
+
+type appHealthResponse struct {
+	models.AppHealth
+}
+
+type MetricsResponse struct {
+	prometheus.Metrics
+}

pkg/apis/tenant/v1alpha2/register.go

@@ -20,11 +20,18 @@ package v1alpha2
 import (
 	"github.com/emicklei/go-restful"
 	"github.com/emicklei/go-restful-openapi"
+	"k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/runtime/schema"
+	"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"
+
+
 	"net/http"
 )
 
@@ -42,52 +49,62 @@ var (
 
 func addWebService(c *restful.Container) error {
 	tags := []string{"Tenant"}
+	ok := "ok"
 	ws := runtime.NewWebService(GroupVersion)
 
 	ws.Route(ws.GET("/workspaces").
 		To(tenant.ListWorkspaces).
+		Returns(http.StatusOK, ok, models.PageableResponse{}).
 		Doc("List workspace by user").
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.GET("/workspaces/{workspace}").
 		To(tenant.DescribeWorkspace).
 		Doc("Get workspace detail").
+		Returns(http.StatusOK, ok, v1alpha1.Workspace{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	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))
 	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))
 	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))
 	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))
 	ws.Route(ws.GET("/workspaces/{workspace}/members/{username}/namespaces").
 		To(tenant.ListNamespaces).
 		Param(ws.PathParameter("workspace", "workspace name")).
 		Param(ws.PathParameter("username", "workspace member's username")).
 		Doc("List the namespaces for the workspace member").
+		Returns(http.StatusOK, ok, []v1.Namespace{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	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))
 	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))
 
 	ws.Route(ws.GET("/workspaces/{workspace}/devops").
@@ -101,8 +118,7 @@ func addWebService(c *restful.Container) error {
 			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).
@@ -115,9 +131,8 @@ func addWebService(c *restful.Container) error {
 		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").
-		Writes([]devops.DevOpsProject{}).
-		Returns(http.StatusOK, RespOK, []devops.DevOpsProject{}).
 		Metadata(restfulspec.KeyOpenAPITags, tags))
 	ws.Route(ws.POST("/workspaces/{workspace}/devops").
 		To(tenant.CreateDevopsProject).

pkg/apiserver/iam/am.go

@@ -31,8 +31,8 @@ import (
 )
 
 type RoleList struct {
-	ClusterRoles []*v1.ClusterRole `json:"clusterRole" protobuf:"bytes,2,rep,name=clusterRoles"`
-	Roles        []*v1.Role        `json:"roles" protobuf:"bytes,2,rep,name=roles"`
+	ClusterRoles []*v1.ClusterRole `json:"clusterRole" description:"cluster role list"`
+	Roles        []*v1.Role        `json:"roles" description:"role list"`
 }
 
 func ListRoleUsers(req *restful.Request, resp *restful.Response) {

pkg/apiserver/iam/auth.go

@@ -30,24 +30,24 @@ import (
 )
 
 type Spec struct {
-	Token string `json:"token"`
+	Token string `json:"token" description:"access token"`
 }
 
 type Status struct {
-	Authenticated bool                   `json:"authenticated"`
-	User          map[string]interface{} `json:"user,omitempty"`
+	Authenticated bool                   `json:"authenticated" description:"is authenticated"`
+	User          map[string]interface{} `json:"user,omitempty" description:"user info"`
 }
 
 type TokenReview struct {
-	APIVersion string  `json:"apiVersion"`
-	Kind       string  `json:"kind"`
+	APIVersion string  `json:"apiVersion" description:"Kubernetes API version"`
+	Kind       string  `json:"kind" description:"kind of the API object"`
 	Spec       *Spec   `json:"spec,omitempty"`
-	Status     *Status `json:"status,omitempty"`
+	Status     *Status `json:"status,omitempty" description:"token review status"`
 }
 
 type LoginRequest struct {
-	Username string `json:"username"`
-	Password string `json:"password"`
+	Username string `json:"username" description:"username"`
+	Password string `json:"password" description:"password"`
 }
 
 const (

pkg/errors/errors.go

@@ -25,7 +25,7 @@ import (
 )
 
 type Error struct {
-	Message string `json:"message"`
+	Message string `json:"message" description:"error message"`
 }
 
 var None = Error{Message: "success"}

pkg/models/applications/applications.go

@@ -38,28 +38,28 @@ import (
 )
 
 type Application struct {
-	Name        string            `json:"name"`
-	RepoName    string            `json:"repoName"`
-	Runtime     string            `json:"namespace"`
-	RuntimeId   string            `json:"runtime_id"`
-	Version     string            `json:"version"`
-	VersionId   string            `json:"version_id"`
-	Status      string            `json:"status"`
-	UpdateTime  time.Time         `json:"updateTime"`
-	CreateTime  time.Time         `json:"createTime"`
-	App         string            `json:"app"`
-	AppId       string            `json:"app_id"`
-	Description string            `json:"description,omitempty"`
-	WorkLoads   *workLoads        `json:"workloads,omitempty"`
-	Services    []v1.Service      `json:"services,omitempty"`
-	Ingresses   []v1beta1.Ingress `json:"ingresses,omitempty"`
-	ClusterID   string            `json:"cluster_id"`
+	Name        string            `json:"name" description:"application name"`
+	RepoName    string            `json:"repoName" description:"repo name"`
+	Runtime     string            `json:"namespace" description:"namespace"`
+	RuntimeId   string            `json:"runtime_id" description:"runtime id"`
+	Version     string            `json:"version" description:"application version"`
+	VersionId   string            `json:"version_id" description:"application version id"`
+	Status      string            `json:"status" description:"application status"`
+	UpdateTime  time.Time         `json:"updateTime" description:"update time"`
+	CreateTime  time.Time         `json:"createTime" description:"create name"`
+	App         string            `json:"app" description:"application template name"`
+	AppId       string            `json:"app_id" description:"application template id"`
+	Description string            `json:"description,omitempty" description:"application description"`
+	WorkLoads   *workLoads        `json:"workloads,omitempty" description:"application workloads"`
+	Services    []v1.Service      `json:"services,omitempty" description:"application services"`
+	Ingresses   []v1beta1.Ingress `json:"ingresses,omitempty" description:"application ingresses"`
+	ClusterID   string            `json:"cluster_id" description:"application id"`
 }
 
 type workLoads struct {
-	Deployments  []appsv1.Deployment  `json:"deployments,omitempty"`
-	Statefulsets []appsv1.StatefulSet `json:"statefulsets,omitempty"`
-	Daemonsets   []appsv1.DaemonSet   `json:"daemonsets,omitempty"`
+	Deployments  []appsv1.Deployment  `json:"deployments,omitempty" description:"deployment list"`
+	Statefulsets []appsv1.StatefulSet `json:"statefulsets,omitempty" description:"statefulset list"`
+	Daemonsets   []appsv1.DaemonSet   `json:"daemonsets,omitempty" description:"daemonset list"`
 }
 
 func ListApplication(runtimeId string, conditions *params.Conditions, limit, offset int) (*models.PageableResponse, error) {

pkg/models/git/git.go

@@ -11,8 +11,8 @@ import (
 )
 
 type AuthInfo struct {
-	RemoteUrl string                  `json:"remoteUrl"`
-	SecretRef *corev1.SecretReference `json:"secretRef,omitempty"`
+	RemoteUrl string                  `json:"remoteUrl" description:"git server url"`
+	SecretRef *corev1.SecretReference `json:"secretRef,omitempty" description:"auth secret reference"`
 }
 
 func GitReadVerify(namespace string, authInfo AuthInfo) error {

pkg/models/log/types.go

@@ -48,6 +48,6 @@ type FluentbitFiltersResult struct {
 }
 
 type FluentbitOutputsResult struct {
-	Status  int               `json:"status"`
-	Outputs []fb.OutputPlugin `json:"outputs,omitempty"`
+	Status  int               `json:"status" description:"response status"`
+	Outputs []fb.OutputPlugin `json:"outputs,omitempty" description:"array of fluent bit output plugins"`
 }

pkg/models/metrics/metrics.go

@@ -47,19 +47,19 @@ const (
 )
 
 type FormatedLevelMetric struct {
-	MetricsLevel string           `json:"metrics_level"`
-	Results      []FormatedMetric `json:"results"`
+	MetricsLevel string           `json:"metrics_level" description:"metrics level, eg. cluster"`
+	Results      []FormatedMetric `json:"results" description:"actual array of results"`
 }
 
 type FormatedMetric struct {
-	MetricName string             `json:"metric_name,omitempty"`
-	Status     string             `json:"status"`
-	Data       FormatedMetricData `json:"data,omitempty"`
+	MetricName string             `json:"metric_name,omitempty" description:"metrics name, eg. scheduler_up_sum"`
+	Status     string             `json:"status" description:"result status, one of error, success"`
+	Data       FormatedMetricData `json:"data,omitempty" description:"actual metrics result"`
 }
 
 type FormatedMetricData struct {
-	Result     []map[string]interface{} `json:"result"`
-	ResultType string                   `json:"resultType"`
+	Result     []map[string]interface{} `json:"result" description:"result presenting metric labels, a series of time points and their instant values"`
+	ResultType string                   `json:"resultType" description:"result type, one of matrix, vector"`
 }
 
 type MetricResultValues []MetricResultValue

pkg/models/registries/registries.go

@@ -28,9 +28,9 @@ import (
 )
 
 type AuthInfo struct {
-	Username   string `json:"username"`
-	Password   string `json:"password"`
-	ServerHost string `json:"serverhost"`
+	Username   string `json:"username" description:"username"`
+	Password   string `json:"password" description:"password"`
+	ServerHost string `json:"serverhost" description:"registry server host"`
 }
 
 const loginSuccess = "Login Succeeded"

pkg/models/status/status.go

@@ -26,14 +26,14 @@ import (
 	"kubesphere.io/kubesphere/pkg/models/resources"
 )
 
-type workLoadStatus struct {
-	Namespace string                 `json:"namespace"`
-	Count     map[string]int         `json:"data"`
-	Items     map[string]interface{} `json:"items,omitempty"`
+type WorkLoadStatus struct {
+	Namespace string                 `json:"namespace" description:"namespace"`
+	Count     map[string]int         `json:"data" description:"unhealthy workload count"`
+	Items     map[string]interface{} `json:"items,omitempty" description:"unhealthy workloads"`
 }
 
-func GetNamespacesResourceStatus(namespace string) (*workLoadStatus, error) {
-	res := workLoadStatus{Count: make(map[string]int), Namespace: namespace, Items: make(map[string]interface{})}
+func GetNamespacesResourceStatus(namespace string) (*WorkLoadStatus, error) {
+	res := WorkLoadStatus{Count: make(map[string]int), Namespace: namespace, Items: make(map[string]interface{})}
 	var notReadyList *models.PageableResponse
 	var err error
 	for _, resource := range []string{resources.Deployments, resources.StatefulSets, resources.DaemonSets, resources.PersistentVolumeClaims, resources.Jobs} {
@@ -61,7 +61,7 @@ func GetNamespacesResourceStatus(namespace string) (*workLoadStatus, error) {
 	return &res, nil
 }
 
-func GetClusterResourceStatus() (*workLoadStatus, error) {
+func GetClusterResourceStatus() (*WorkLoadStatus, error) {
 
 	return GetNamespacesResourceStatus("")
 }

pkg/models/types.go

@@ -25,8 +25,8 @@ import (
 )
 
 type PageableResponse struct {
-	Items      []interface{} `json:"items"`
-	TotalCount int           `json:"total_count"`
+	Items      []interface{} `json:"items" description:"paging data"`
+	TotalCount int           `json:"total_count" description:"total count"`
 }
 
 type Workspace struct {
@@ -47,8 +47,8 @@ type Rule struct {
 }
 
 type SimpleRule struct {
-	Name    string   `json:"name"`
-	Actions []string `json:"actions"`
+	Name    string   `json:"name" description:"rule name"`
+	Actions []string `json:"actions" description:"actions"`
 }
 
 type User struct {
@@ -82,26 +82,26 @@ type Group struct {
 }
 
 type Component struct {
-	Name            string      `json:"name"`
-	Namespace       string      `json:"namespace"`
-	SelfLink        string      `json:"selfLink"`
-	Label           interface{} `json:"label"`
-	StartedAt       time.Time   `json:"startedAt"`
-	TotalBackends   int         `json:"totalBackends"`
-	HealthyBackends int         `json:"healthyBackends"`
+	Name            string      `json:"name" description:"component name"`
+	Namespace       string      `json:"namespace" description:"namespace"`
+	SelfLink        string      `json:"selfLink" description:"self link"`
+	Label           interface{} `json:"label" description:"labels"`
+	StartedAt       time.Time   `json:"startedAt" description:"started time"`
+	TotalBackends   int         `json:"totalBackends" description:"total backends"`
+	HealthyBackends int         `json:"healthyBackends" description:"healthy backends"`
 }
 
 type PodInfo struct {
-	Namespace string `json:"namespace"`
-	Pod       string `json:"pod"`
-	Container string `json:"container"`
+	Namespace string `json:"namespace" description:"namespace"`
+	Pod       string `json:"pod" description:"pod name"`
+	Container string `json:"container" description:"container name"`
 }
 
 type Token struct {
-	Token string `json:"access_token"`
+	Token string `json:"access_token" description:"access token"`
 }
 
 type ResourceQuota struct {
-	Namespace string                     `json:"namespace"`
-	Data      corev1.ResourceQuotaStatus `json:"data"`
+	Namespace string                     `json:"namespace" description:"namespace"`
+	Data      corev1.ResourceQuotaStatus `json:"data" description:"resource quota status"`
 }

pkg/simple/client/elasticsearch/esclient.go

@@ -286,49 +286,49 @@ func createQueryRequest(param QueryParameters) (int, []byte, error) {
 }
 
 type Response struct {
-	Status       int             `json:"status"`
-	Workspace    string          `json:"workspace,omitempty"`
-	Shards       Shards          `json:"_shards"`
-	Hits         Hits            `json:"hits"`
-	Aggregations json.RawMessage `json:"aggregations"`
+	Status       int             `json:"status" description:"query status"`
+	Workspace    string          `json:"workspace,omitempty" description:"workspace the query was performed against"`
+	Shards       Shards          `json:"_shards" description:"tells shard information"`
+	Hits         Hits            `json:"hits" description:"search results"`
+	Aggregations json.RawMessage `json:"aggregations" description:"aggregation results"`
 }
 
 type Shards struct {
-	Total      int64 `json:"total"`
-	Successful int64 `json:"successful"`
-	Skipped    int64 `json:"skipped"`
-	Failed     int64 `json:"failed"`
+	Total      int64 `json:"total" description:"tells how many shards were searched"`
+	Successful int64 `json:"successful" description:"count of the successful searched shards"`
+	Skipped    int64 `json:"skipped" description:"count of the skipped searched shards"`
+	Failed     int64 `json:"failed" description:"count of the failed searched shards"`
 }
 
 type Hits struct {
-	Total int64 `json:"total"`
-	Hits  []Hit `json:"hits"`
+	Total int64 `json:"total" description:"total number of documents matching our search criteria"`
+	Hits  []Hit `json:"hits" description:"actual array of search results"`
 }
 
 type Hit struct {
-	Source    Source    `json:"_source"`
-	HighLight HighLight `json:"highlight"`
-	Sort      []int64   `json:"sort"`
+	Source    Source    `json:"_source" description:"search result item"`
+	HighLight HighLight `json:"highlight" description:"highlighted log fragment"`
+	Sort      []int64   `json:"sort" description:"sort key for results"`
 }
 
 type Source struct {
-	Log        string     `json:"log"`
-	Time       string     `json:"time"`
-	Kubernetes Kubernetes `json:"kubernetes"`
+	Log        string     `json:"log" description:"the log message"`
+	Time       string     `json:"time" description:"log timestamp"`
+	Kubernetes Kubernetes `json:"kubernetes" description:"kubernetes addon information on the log"`
 }
 
 type Kubernetes struct {
-	Namespace string `json:"namespace_name"`
-	Pod       string `json:"pod_name"`
-	Container string `json:"container_name"`
-	Host      string `json:"host"`
+	Namespace string `json:"namespace_name" description:"the namespace the log is from"`
+	Pod       string `json:"pod_name" description:"the pod the log is from"`
+	Container string `json:"container_name" description:"the container the log is from"`
+	Host      string `json:"host" description:"the node the log if from"`
 }
 
 type HighLight struct {
-	LogHighLights       []string `json:"log,omitempty"`
-	NamespaceHighLights []string `json:"kubernetes.namespace_name.keyword,omitempty"`
-	PodHighLights       []string `json:"kubernetes.pod_name.keyword,omitempty"`
-	ContainerHighLights []string `json:"kubernetes.container_name.keyword,omitempty"`
+	LogHighLights       []string `json:"log,omitempty" description:"log messages to highlight"`
+	NamespaceHighLights []string `json:"kubernetes.namespace_name.keyword,omitempty" description:"namespaces to highlight"`
+	PodHighLights       []string `json:"kubernetes.pod_name.keyword,omitempty" description:"pods to highlight"`
+	ContainerHighLights []string `json:"kubernetes.container_name.keyword,omitempty" description:"containers to highlight"`
 }
 
 type LogRecord struct {

pkg/simple/client/fluentbit/fluentbitcrdclient.go

@@ -64,24 +64,24 @@ type FluentBitStatus struct {
 
 // Plugin struct for fluent-bit plugins
 type Plugin struct {
-	Type       string      `json:"type"`
-	Name       string      `json:"name"`
-	Parameters []Parameter `json:"parameters"`
+	Type       string      `json:"type" description:"output plugin type, eg. fluentbit-output-es"`
+	Name       string      `json:"name" description:"output plugin name, eg. fluentbit-output-es"`
+	Parameters []Parameter `json:"parameters" description:"output plugin configuration parameters"`
 }
 
 // Fluent-bit output plugins
 type OutputPlugin struct {
 	Plugin
-	Id         string    `json:"id"`
-	Enable     bool      `json:"enable"`
-	Updatetime time.Time `json:"updatetime,omitempty"`
+	Id         string    `json:"id,omitempty" description:"output plugin uuid"`
+	Enable     bool      `json:"enable" description:"current output plugin status, one of true, false"`
+	Updatetime time.Time `json:"updatetime,omitempty" description:"last updatetime of the output plugin"`
 }
 
 // Parameter generic parameter type to handle values from different sources
 type Parameter struct {
-	Name      string     `json:"name"`
+	Name      string     `json:"name" description:"configuration parameter key, eg. Name. refer to fluent bit official doc for more information."`
 	ValueFrom *ValueFrom `json:"valueFrom,omitempty"`
-	Value     string     `json:"value"`
+	Value     string     `json:"value" description:"configuration parameter value, eg. es. refer to fluent bit official doc for more information."`
 }
 
 // ValueFrom generic type to determine value origin