Merge branch 'bees' into koh

endpoints/api/user.py

@@ -9,7 +9,7 @@ from app import app, billing as stripe, authentication, avatar
 from endpoints.api import (ApiResource, nickname, resource, validate_json_request, request_error,
                            log_action, internal_only, NotFound, require_user_admin, parse_args,
                            query_param, InvalidToken, require_scope, format_date, hide_if, show_if,
-                           license_error,  require_fresh_login)
+                           license_error,  require_fresh_login, path_param, define_json_response)
 from endpoints.api.subscribe import subscribe
 from endpoints.common import common_login
 from endpoints.api.team import try_accept_invite
@@ -59,13 +59,13 @@ def user_view(user):
     'verified': user.verified,
     'anonymous': False,
     'username': user.username,
-    'email': user.email,
     'avatar': avatar.compute_hash(user.email, name=user.username),
   }
 
   user_admin = UserAdminPermission(user.username)
   if user_admin.can():
     user_response.update({
+      'email': user.email,
       'organizations': [org_view(o) for o in organizations],
       'logins': [login_view(login) for login in logins],
       'can_create_repo': True,
@@ -148,10 +148,51 @@ class User(ApiResource):
         },
       },
     },
+    'UserView': {
+      'id': 'UserView',
+      'type': 'object',
+      'description': 'Describes a user',
+      'required': ['verified', 'anonymous', 'gravatar'],
+      'properties': {
+        'verified': {
+          'type': 'boolean',
+          'description': 'Whether the user\'s email address has been verified'
+        },
+        'anonymous': {
+          'type': 'boolean',
+          'description': 'true if this user data represents a guest user'
+        },
+        'email': {
+          'type': 'string',
+          'description': 'The user\'s email address',
+        },
+        'gravatar': {
+          'type': 'string',
+          'description': 'Gravatar hash representing the user\'s icon'
+        },
+        'organizations': {
+          'type': 'array',
+          'description': 'Information about the organizations in which the user is a member'
+        },
+        'logins': {
+          'type': 'array',
+          'description': 'The list of external login providers against which the user has authenticated'
+        },
+        'can_create_repo': {
+          'type': 'boolean',
+          'description': 'Whether the user has permission to create repositories'
+        },
+        'preferred_namespace': {
+          'type': 'boolean',
+          'description': 'If true, the user\'s namespace is the preferred namespace to display'
+        }
+      }
+    },
   }
 
   @require_scope(scopes.READ_USER)
   @nickname('getLoggedInUser')
+  @define_json_response('UserView')
   def get(self):
     """ Get user information for the authenticated user. """
     user = get_authenticated_user()
@@ -165,6 +206,7 @@ class User(ApiResource):
   @nickname('changeUserDetails')
   @internal_only
   @validate_json_request('UpdateUser')
+  @define_json_response('UserView')
   def put(self):
     """ Update a users details such as password or email. """
     user = get_authenticated_user()
@@ -525,6 +567,7 @@ class UserNotificationList(ApiResource):
 
 
 @resource('/v1/user/notifications/<uuid>')
+@path_param('uuid', 'The uuid of the user notification')
 @internal_only
 class UserNotification(ApiResource):
   schemas = {
@@ -597,6 +640,7 @@ class UserAuthorizationList(ApiResource):
 
 
 @resource('/v1/user/authorizations/<access_token_uuid>')
+@path_param('access_token_uuid', 'The uuid of the access token')
 @internal_only
 class UserAuthorization(ApiResource):
   @require_user_admin