From 468ef322d1fbda4ca3c00e72cf5e49a3ec658054 Mon Sep 17 00:00:00 2001 From: hongming Date: Thu, 6 Jun 2019 18:35:57 +0800 Subject: [PATCH] update api doc Signed-off-by: hongming --- pkg/apis/iam/v1alpha2/register.go | 102 +++++++++++++++++------ pkg/apis/operations/v1alpha2/register.go | 11 +-- pkg/apis/resources/v1alpha2/register.go | 49 ++++++----- pkg/apis/tenant/v1alpha2/register.go | 20 +++++ pkg/apiserver/iam/am.go | 4 +- pkg/apiserver/iam/auth.go | 16 ++-- pkg/errors/errors.go | 2 +- pkg/models/applications/applications.go | 38 ++++----- pkg/models/git/git.go | 4 +- pkg/models/registries/registries.go | 6 +- pkg/models/status/status.go | 14 ++-- pkg/models/types.go | 34 ++++---- 12 files changed, 190 insertions(+), 110 deletions(-) diff --git a/pkg/apis/iam/v1alpha2/register.go b/pkg/apis/iam/v1alpha2/register.go index bb3ff2460..c6f66ebe5 100644 --- a/pkg/apis/iam/v1alpha2/register.go +++ b/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 diff --git a/pkg/apis/operations/v1alpha2/register.go b/pkg/apis/operations/v1alpha2/register.go index a42ddca9c..b3b23d755 100644 --- a/pkg/apis/operations/v1alpha2/register.go +++ b/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) diff --git a/pkg/apis/resources/v1alpha2/register.go b/pkg/apis/resources/v1alpha2/register.go index 0f0445917..58487eec0 100644 --- a/pkg/apis/resources/v1alpha2/register.go +++ b/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) diff --git a/pkg/apis/tenant/v1alpha2/register.go b/pkg/apis/tenant/v1alpha2/register.go index 85684aff6..322f077f4 100644 --- a/pkg/apis/tenant/v1alpha2/register.go +++ b/pkg/apis/tenant/v1alpha2/register.go @@ -20,9 +20,15 @@ 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/errors" + "kubesphere.io/kubesphere/pkg/models" + "kubesphere.io/kubesphere/pkg/models/devops" + "net/http" ) const GroupName = "tenant.kubesphere.io" @@ -36,74 +42,88 @@ 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"). To(tenant.ListDevopsProjects). Param(ws.PathParameter("workspace", "workspace name")). Doc("List devops projects for the current user"). + Returns(http.StatusOK, ok, models.PageableResponse{}). Metadata(restfulspec.KeyOpenAPITags, tags)) ws.Route(ws.GET("/workspaces/{workspace}/members/{username}/devops"). To(tenant.ListDevopsProjects). Param(ws.PathParameter("workspace", "workspace name")). Param(ws.PathParameter("username", "workspace member's username")). + Returns(http.StatusOK, ok, models.PageableResponse{}). Doc("List the devops projects for the workspace member"). Metadata(restfulspec.KeyOpenAPITags, tags)) ws.Route(ws.POST("/workspaces/{workspace}/devops"). To(tenant.CreateDevopsProject). Param(ws.PathParameter("workspace", "workspace name")). Doc("Create devops project"). + Returns(http.StatusOK, ok, devops.DevOpsProject{}). Metadata(restfulspec.KeyOpenAPITags, tags)) ws.Route(ws.DELETE("/workspaces/{workspace}/devops/{id}"). To(tenant.DeleteDevopsProject). Param(ws.PathParameter("workspace", "workspace name")). Doc("Delete devops project"). + Returns(http.StatusOK, ok, errors.Error{}). Metadata(restfulspec.KeyOpenAPITags, tags)) ws.Route(ws.GET("/logging"). To(tenant.LogQuery). diff --git a/pkg/apiserver/iam/am.go b/pkg/apiserver/iam/am.go index a86966593..51aa7b4b6 100644 --- a/pkg/apiserver/iam/am.go +++ b/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) { diff --git a/pkg/apiserver/iam/auth.go b/pkg/apiserver/iam/auth.go index 2d463f173..49245654e 100644 --- a/pkg/apiserver/iam/auth.go +++ b/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 ( diff --git a/pkg/errors/errors.go b/pkg/errors/errors.go index 75bab86a9..437bdfb62 100644 --- a/pkg/errors/errors.go +++ b/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"} diff --git a/pkg/models/applications/applications.go b/pkg/models/applications/applications.go index dd215fc3b..c90a00cdf 100644 --- a/pkg/models/applications/applications.go +++ b/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) { diff --git a/pkg/models/git/git.go b/pkg/models/git/git.go index 4abeddfec..c4f6a027c 100644 --- a/pkg/models/git/git.go +++ b/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 { diff --git a/pkg/models/registries/registries.go b/pkg/models/registries/registries.go index 4c31b7853..32df98fca 100644 --- a/pkg/models/registries/registries.go +++ b/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" diff --git a/pkg/models/status/status.go b/pkg/models/status/status.go index 9e90b68de..040f09499 100644 --- a/pkg/models/status/status.go +++ b/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("") } diff --git a/pkg/models/types.go b/pkg/models/types.go index bc91ad533..378a8717f 100644 --- a/pkg/models/types.go +++ b/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"` }