update api doc

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

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