From 8e09ab34b54718af7753ba7d7e4e370ab14efa1a Mon Sep 17 00:00:00 2001 From: Syndamia Date: Thu, 4 Feb 2021 15:31:49 +0200 Subject: Added some XML documentation to Service layer (where really needed) --- src/DevHive.Services/Services/CommentService.cs | 15 +++++++++++- src/DevHive.Services/Services/FeedService.cs | 8 +++++++ src/DevHive.Services/Services/PostService.cs | 19 +++++++++++++++ src/DevHive.Services/Services/UserService.cs | 32 +++++++++++++++++++++++++ 4 files changed, 73 insertions(+), 1 deletion(-) (limited to 'src/DevHive.Services') diff --git a/src/DevHive.Services/Services/CommentService.cs b/src/DevHive.Services/Services/CommentService.cs index e0eb88a..1ea775c 100644 --- a/src/DevHive.Services/Services/CommentService.cs +++ b/src/DevHive.Services/Services/CommentService.cs @@ -103,6 +103,9 @@ namespace DevHive.Services.Services #endregion #region Validations + /// + /// Checks whether the user Id in the token and the given user Id match + /// public async Task ValidateJwtForCreating(Guid userId, string rawTokenData) { User user = await this.GetUserForValidation(rawTokenData); @@ -110,6 +113,11 @@ namespace DevHive.Services.Services return user.Id == userId; } + /// + /// Checks whether the comment, gotten with the commentId, + /// is made by the user in the token + /// or if the user in the token is an admin + /// public async Task ValidateJwtForComment(Guid commentId, string rawTokenData) { Comment comment = await this._commentRepository.GetByIdAsync(commentId) ?? @@ -126,6 +134,9 @@ namespace DevHive.Services.Services return false; } + /// + /// Returns the user, via their Id in the token + /// private async Task GetUserForValidation(string rawTokenData) { JwtSecurityToken jwt = new JwtSecurityTokenHandler().ReadJwtToken(rawTokenData.Remove(0, 7)); @@ -139,7 +150,9 @@ namespace DevHive.Services.Services return user; } - + /// + /// Returns all values from a given claim type + /// private List GetClaimTypeValues(string type, IEnumerable claims) { List toReturn = new(); diff --git a/src/DevHive.Services/Services/FeedService.cs b/src/DevHive.Services/Services/FeedService.cs index b9d1922..671df60 100644 --- a/src/DevHive.Services/Services/FeedService.cs +++ b/src/DevHive.Services/Services/FeedService.cs @@ -24,6 +24,10 @@ namespace DevHive.Services.Services this._mapper = mapper; } + /// + /// This method is used in the feed page. + /// See the FeedRepository "GetFriendsPosts" menthod for more information on how it works. + /// public async Task GetPage(GetPageServiceModel model) { User user = null; @@ -53,6 +57,10 @@ namespace DevHive.Services.Services return readPageServiceModel; } + /// + /// This method is used in the profile pages. + /// See the FeedRepository "GetUsersPosts" menthod for more information on how it works. + /// public async Task GetUserPage(GetPageServiceModel model) { User user = null; diff --git a/src/DevHive.Services/Services/PostService.cs b/src/DevHive.Services/Services/PostService.cs index 6dbb272..16d6611 100644 --- a/src/DevHive.Services/Services/PostService.cs +++ b/src/DevHive.Services/Services/PostService.cs @@ -138,6 +138,9 @@ namespace DevHive.Services.Services #endregion #region Validations + /// + /// Checks whether the user Id in the token and the given user Id match + /// public async Task ValidateJwtForCreating(Guid userId, string rawTokenData) { User user = await this.GetUserForValidation(rawTokenData); @@ -145,6 +148,11 @@ namespace DevHive.Services.Services return user.Id == userId; } + /// + /// Checks whether the post, gotten with the postId, + /// is made by the user in the token + /// or if the user in the token is an admin + /// public async Task ValidateJwtForPost(Guid postId, string rawTokenData) { Post post = await this._postRepository.GetByIdAsync(postId) ?? @@ -161,6 +169,11 @@ namespace DevHive.Services.Services return false; } + /// + /// Checks whether the comment, gotten with the commentId, + /// is made by the user in the token + /// or if the user in the token is an admin + /// public async Task ValidateJwtForComment(Guid commentId, string rawTokenData) { Comment comment = await this._commentRepository.GetByIdAsync(commentId) ?? @@ -177,6 +190,9 @@ namespace DevHive.Services.Services return false; } + /// + /// Returns the user, via their Id in the token + /// private async Task GetUserForValidation(string rawTokenData) { JwtSecurityToken jwt = new JwtSecurityTokenHandler().ReadJwtToken(rawTokenData.Remove(0, 7)); @@ -190,6 +206,9 @@ namespace DevHive.Services.Services return user; } + /// + /// Returns all values from a given claim type + /// private List GetClaimTypeValues(string type, IEnumerable claims) { List toReturn = new(); diff --git a/src/DevHive.Services/Services/UserService.cs b/src/DevHive.Services/Services/UserService.cs index ae1760f..3feca9f 100644 --- a/src/DevHive.Services/Services/UserService.cs +++ b/src/DevHive.Services/Services/UserService.cs @@ -47,6 +47,10 @@ namespace DevHive.Services.Services } #region Authentication + /// + /// Adds a new user to the database with the values from the given model. + /// Returns a JSON Web Token (that can be used for authorization) + /// public async Task LoginUser(LoginServiceModel loginModel) { if (!await this._userRepository.DoesUsernameExistAsync(loginModel.UserName)) @@ -60,6 +64,9 @@ namespace DevHive.Services.Services return new TokenModel(WriteJWTSecurityToken(user.Id, user.UserName, user.Roles)); } + /// + /// Returns a new JSON Web Token (that can be used for authorization) for the given user + /// public async Task RegisterUser(RegisterServiceModel registerModel) { if (await this._userRepository.DoesUsernameExistAsync(registerModel.UserName)) @@ -125,6 +132,9 @@ namespace DevHive.Services.Services return this._userMapper.Map(newUser); } + /// + /// Uploads the given picture and assigns it's link to the user in the database + /// public async Task UpdateProfilePicture(UpdateProfilePictureServiceModel updateProfilePictureServiceModel) { User user = await this._userRepository.GetByIdAsync(updateProfilePictureServiceModel.UserId); @@ -162,6 +172,11 @@ namespace DevHive.Services.Services #endregion #region Validations + /// + /// Checks whether the given user, gotten by the "id" property, + /// is the same user as the one in the token (uness the user in the token has the admin role) + /// and the roles in the token are the same as those in the user, gotten by the id in the token + /// public async Task ValidJWT(Guid id, string rawTokenData) { // There is authorization name in the beginning, i.e. "Bearer eyJh..." @@ -197,6 +212,9 @@ namespace DevHive.Services.Services return true; } + /// + /// Returns all values from a given claim type + /// private List GetClaimTypeValues(string type, IEnumerable claims) { List toReturn = new(); @@ -208,6 +226,11 @@ namespace DevHive.Services.Services return toReturn; } + /// + /// Checks whether the user in the model exists + /// and whether the username in the model is already taken. + /// If the check fails (is false), it throws an exception, otherwise nothing happens + /// private async Task ValidateUserOnUpdate(UpdateUserServiceModel updateUserServiceModel) { if (!await this._userRepository.DoesUserExistAsync(updateUserServiceModel.Id)) @@ -218,6 +241,10 @@ namespace DevHive.Services.Services throw new ArgumentException("Username already exists!"); } + /// + /// Return a new JSON Web Token, containing the user id, username and roles. + /// Tokens have an expiration time of 7 days. + /// private string WriteJWTSecurityToken(Guid userId, string username, HashSet roles) { byte[] signingKey = Encoding.ASCII.GetBytes(_jwtOptions.Secret); @@ -274,6 +301,11 @@ namespace DevHive.Services.Services return new TokenModel(WriteJWTSecurityToken(newUser.Id, newUser.UserName, newUser.Roles)); } + /// + /// Returns the user with the Id in the model, adding to him the roles, languages and technologies, specified by the parameter model. + /// This practically maps HashSet to HashSet (and the equvalent HashSets for Languages and Technologies) + /// and assigns the latter to the returned user. + /// private async Task PopulateModel(UpdateUserServiceModel updateUserServiceModel) { User user = this._userMapper.Map(updateUserServiceModel); -- cgit v1.2.3