add descriptions on all api endpoints

src/Host/Controllers/Catalog/BrandsController.cs

@@ -6,7 +6,7 @@ public class BrandsController : VersionedApiController
 {
     [HttpPost("search")]
     [MustHavePermission(FSHAction.Search, FSHResource.Brands)]
-    [OpenApiOperation("Search Brands using available Filters.", "")]
+    [OpenApiOperation("Search brands using available filters.", "")]
     public Task<PaginationResponse<BrandDto>> SearchAsync(SearchBrandsRequest request)
     {
         return Mediator.Send(request);

src/Host/Controllers/Dashboard/DashboardController.cs

@@ -6,6 +6,7 @@ public class DashboardController : VersionedApiController
 {
     [HttpGet]
     [MustHavePermission(FSHAction.View, FSHResource.Dashboard)]
+    [OpenApiOperation("Get statistics for the dashboard.", "")]
     public Task<StatsDto> GetAsync()
     {
         return Mediator.Send(new GetStatsRequest());

src/Host/Controllers/Identity/ProfileController.cs

@@ -13,6 +13,7 @@ public ProfileController(IProfileService profileService, IUserService userServic
         (_profileService, _userService) = (profileService, userService);
 
     [HttpGet]
+    [OpenApiOperation("Get profile details of currently logged in user.", "")]
     public async Task<ActionResult<UserDetailsDto>> GetAsync(CancellationToken cancellationToken)
     {
         return User.GetUserId() is not { } userId || string.IsNullOrEmpty(userId)
@@ -22,6 +23,7 @@ public async Task<ActionResult<UserDetailsDto>> GetAsync(CancellationToken cance
 
     [HttpPost]
     [AllowAnonymous]
+    [OpenApiOperation("Create a new profile.", "")]
     public Task<string> CreateAsync(CreateProfileRequest request)
     {
         // TODO: check if registering anonymous users is actually allowed (should probably be an appsetting)
@@ -31,6 +33,7 @@ public Task<string> CreateAsync(CreateProfileRequest request)
     }
 
     [HttpPut]
+    [OpenApiOperation("Update an existing profile.", "")]
     public async Task<ActionResult> UpdateAsync(UpdateProfileRequest request)
     {
         if (User.GetUserId() is not { } userId || string.IsNullOrEmpty(userId))
@@ -44,6 +47,7 @@ public async Task<ActionResult> UpdateAsync(UpdateProfileRequest request)
 
     [HttpGet("confirm-email")]
     [AllowAnonymous]
+    [OpenApiOperation("Confirm email address for a profile.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Search))]
     public Task<string> ConfirmEmailAsync([FromQuery] string userId, [FromQuery] string code, [FromQuery] string tenant, CancellationToken cancellationToken)
     {
@@ -52,6 +56,7 @@ public Task<string> ConfirmEmailAsync([FromQuery] string userId, [FromQuery] str
 
     [HttpGet("confirm-phone-number")]
     [AllowAnonymous]
+    [OpenApiOperation("Confirm phone number for a profile.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Search))]
     public Task<string> ConfirmPhoneNumberAsync([FromQuery] string userId, [FromQuery] string code)
     {
@@ -61,20 +66,23 @@ public Task<string> ConfirmPhoneNumberAsync([FromQuery] string userId, [FromQuer
     [HttpPost("forgot-password")]
     [AllowAnonymous]
     [TenantIdHeader]
+    [OpenApiOperation("Request a pasword reset email.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
     public Task<string> ForgotPasswordAsync(ForgotPasswordRequest request)
     {
         return _profileService.ForgotPasswordAsync(request, GetOriginFromRequest());
     }
 
     [HttpPost("reset-password")]
+    [OpenApiOperation("Reset your password.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
     public Task<string> ResetPasswordAsync(ResetPasswordRequest request)
     {
         return _profileService.ResetPasswordAsync(request);
     }
 
     [HttpPut("change-password")]
+    [OpenApiOperation("Change your password.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
     public async Task<ActionResult> ChangePasswordAsync(ChangePasswordRequest model)
     {

src/Host/Controllers/Identity/RolesController.cs

@@ -10,27 +10,31 @@ public class RolesController : VersionNeutralApiController
 
     [HttpGet]
     [MustHavePermission(FSHAction.View, FSHResource.Roles)]
+    [OpenApiOperation("Get a list of all roles.", "")]
     public Task<List<RoleDto>> GetListAsync(CancellationToken cancellationToken)
     {
         return _roleService.GetListAsync(cancellationToken);
     }
 
     [HttpGet("{id}")]
     [MustHavePermission(FSHAction.View, FSHResource.Roles)]
+    [OpenApiOperation("Get role details.", "")]
     public Task<RoleDto> GetByIdAsync(string id)
     {
         return _roleService.GetByIdAsync(id);
     }
 
     [HttpGet("{id}/permissions")]
     [MustHavePermission(FSHAction.View, FSHResource.RoleClaims)]
+    [OpenApiOperation("Get role details with its permissions.", "")]
     public Task<RoleDto> GetByIdWithPermissionsAsync(string id, CancellationToken cancellationToken)
     {
         return _roleService.GetByIdWithPermissionsAsync(id, cancellationToken);
     }
 
     [HttpPut("{id}/permissions")]
     [MustHavePermission(FSHAction.Update, FSHResource.RoleClaims)]
+    [OpenApiOperation("Update a role's permissions.", "")]
     public async Task<ActionResult<string>> UpdatePermissionsAsync(string id, UpdateRolePermissionsRequest request, CancellationToken cancellationToken)
     {
         if (id != request.RoleId)
@@ -43,13 +47,15 @@ public async Task<ActionResult<string>> UpdatePermissionsAsync(string id, Update
 
     [HttpPost]
     [MustHavePermission(FSHAction.Create, FSHResource.Roles)]
+    [OpenApiOperation("Create or update a role.", "")]
     public Task<string> RegisterRoleAsync(CreateOrUpdateRoleRequest request)
     {
         return _roleService.CreateOrUpdateAsync(request);
     }
 
     [HttpDelete("{id}")]
     [MustHavePermission(FSHAction.Delete, FSHResource.Roles)]
+    [OpenApiOperation("Delete a role.", "")]
     public Task<string> DeleteAsync(string id)
     {
         return _roleService.DeleteAsync(id);

src/Host/Controllers/Identity/TokensController.cs

@@ -11,7 +11,7 @@ public sealed class TokensController : VersionNeutralApiController
     [HttpPost]
     [AllowAnonymous]
     [TenantIdHeader]
-    [OpenApiOperation("Submit Credentials with Tenant Id to generate valid Access Token.", "")]
+    [OpenApiOperation("Request an access token using credentials.", "")]
     public Task<TokenResponse> GetTokenAsync(TokenRequest request, CancellationToken cancellationToken)
     {
         return _tokenService.GetTokenAsync(request, GetIpAddress(), cancellationToken);
@@ -20,6 +20,7 @@ public Task<TokenResponse> GetTokenAsync(TokenRequest request, CancellationToken
     [HttpPost("refresh")]
     [AllowAnonymous]
     [TenantIdHeader]
+    [OpenApiOperation("Request an access token using a refresh token.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Search))]
     public Task<TokenResponse> RefreshAsync(RefreshTokenRequest request)
     {

src/Host/Controllers/Identity/UsersController.cs

@@ -10,20 +10,23 @@ public class UsersController : VersionNeutralApiController
 
     [HttpGet]
     [MustHavePermission(FSHAction.View, FSHResource.Users)]
+    [OpenApiOperation("Get list of all users.", "")]
     public Task<List<UserDetailsDto>> GetListAsync(CancellationToken cancellationToken)
     {
         return _userService.GetListAsync(cancellationToken);
     }
 
     [HttpGet("{id}")]
     [MustHavePermission(FSHAction.View, FSHResource.Users)]
+    [OpenApiOperation("Get user details.", "")]
     public Task<UserDetailsDto> GetByIdAsync(string id, CancellationToken cancellationToken)
     {
         return _userService.GetAsync(id, cancellationToken);
     }
 
     [HttpGet("{id}/roles")]
     [MustHavePermission(FSHAction.View, FSHResource.UserRoles)]
+    [OpenApiOperation("Get a user's roles.", "")]
     public Task<List<UserRoleDto>> GetRolesAsync(string id, CancellationToken cancellationToken)
     {
         return _userService.GetRolesAsync(id, cancellationToken);
@@ -32,16 +35,24 @@ public Task<List<UserRoleDto>> GetRolesAsync(string id, CancellationToken cancel
     [HttpPost("{id}/roles")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
     [MustHavePermission(FSHAction.Update, FSHResource.UserRoles)]
+    [OpenApiOperation("Change a user's assigned roles.", "")]
     public Task<string> AssignRolesAsync(string id, UserRolesRequest request, CancellationToken cancellationToken)
     {
         return _userService.AssignRolesAsync(id, request, cancellationToken);
     }
 
-    [HttpPost("toggle-status")]
+    [HttpPost("{id}/toggle-status")]
     [MustHavePermission(FSHAction.Update, FSHResource.Users)]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
-    public Task ToggleUserStatusAsync(ToggleUserStatusRequest request, CancellationToken cancellationToken)
+    [OpenApiOperation("Toggle a user's active status.", "")]
+    public async Task<ActionResult> ToggleUserStatusAsync(string id, ToggleUserStatusRequest request, CancellationToken cancellationToken)
     {
-        return _userService.ToggleStatusAsync(request, cancellationToken);
+        if (id != request.UserId)
+        {
+            return BadRequest();
+        }
+
+        await _userService.ToggleStatusAsync(request, cancellationToken);
+        return Ok();
     }
 }

src/Host/Controllers/Multitenancy/TenantsController.cs

@@ -6,53 +6,53 @@ public class TenantsController : VersionNeutralApiController
 {
     [HttpGet]
     [MustHavePermission(FSHAction.View, FSHResource.Tenants)]
-    [OpenApiOperation("Get all the available Tenants.", "")]
+    [OpenApiOperation("Get a list of all tenants.", "")]
     public Task<List<TenantDto>> GetListAsync()
     {
         return Mediator.Send(new GetAllTenantsRequest());
     }
 
-    [HttpGet("{tenantId}")]
+    [HttpGet("{id}")]
     [MustHavePermission(FSHAction.View, FSHResource.Tenants)]
-    [OpenApiOperation("Get Tenant Details.", "")]
-    public Task<TenantDto> GetAsync(string tenantId)
+    [OpenApiOperation("Get tenant details.", "")]
+    public Task<TenantDto> GetAsync(string id)
     {
-        return Mediator.Send(new GetTenantRequest(tenantId));
+        return Mediator.Send(new GetTenantRequest(id));
     }
 
     [HttpPost]
     [MustHavePermission(FSHAction.Create, FSHResource.Tenants)]
-    [OpenApiOperation("Create a new Tenant.", "")]
+    [OpenApiOperation("Create a new tenant.", "")]
     public Task<string> CreateAsync(CreateTenantRequest request)
     {
         return Mediator.Send(request);
     }
 
-    [HttpPost("{tenantId}/activate")]
+    [HttpPost("{id}/activate")]
     [MustHavePermission(FSHAction.Update, FSHResource.Tenants)]
-    [OpenApiOperation("Activate Tenant.", "")]
+    [OpenApiOperation("Activate a tenant.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
-    public Task<string> ActivateAsync(string tenantId)
+    public Task<string> ActivateAsync(string id)
     {
-        return Mediator.Send(new ActivateTenantRequest(tenantId));
+        return Mediator.Send(new ActivateTenantRequest(id));
     }
 
-    [HttpPost("{tenantId}/deactivate")]
+    [HttpPost("{id}/deactivate")]
     [MustHavePermission(FSHAction.Update, FSHResource.Tenants)]
-    [OpenApiOperation("Deactivate Tenant.", "")]
+    [OpenApiOperation("Deactivate a tenant.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
-    public Task<string> DeactivateAsync(string tenantId)
+    public Task<string> DeactivateAsync(string id)
     {
-        return Mediator.Send(new DeactivateTenantRequest(tenantId));
+        return Mediator.Send(new DeactivateTenantRequest(id));
     }
 
-    [HttpPost("{tenantId}/upgrade")]
+    [HttpPost("{id}/upgrade")]
     [MustHavePermission(FSHAction.UpgradeSubscription, FSHResource.Tenants)]
-    [OpenApiOperation("Upgrade Subscription of Tenant.", "")]
+    [OpenApiOperation("Upgrade a tenant's subscription.", "")]
     [ApiConventionMethod(typeof(FSHApiConventions), nameof(FSHApiConventions.Register))]
-    public async Task<ActionResult<string>> UpgradeSubscriptionAsync(string tenantId, UpgradeSubscriptionRequest request)
+    public async Task<ActionResult<string>> UpgradeSubscriptionAsync(string id, UpgradeSubscriptionRequest request)
     {
-        return tenantId != request.TenantId
+        return id != request.TenantId
             ? BadRequest()
             : Ok(await Mediator.Send(request));
     }

src/Host/Controllers/Personal/PersonalController.cs

@@ -11,12 +11,14 @@ public class PersonalController : VersionNeutralApiController
     public PersonalController(IUserService userService) => _userService = userService;
 
     [HttpGet("logs")]
+    [OpenApiOperation("Get audit logs of currently logged in user.", "")]
     public Task<List<AuditDto>> GetMyLogsAsync()
     {
         return Mediator.Send(new GetMyAuditLogsRequest());
     }
 
     [HttpGet("permissions")]
+    [OpenApiOperation("Get permissions of currently logged in user.", "")]
     public async Task<ActionResult<List<string>>> GetMyPermissionsAsync(CancellationToken cancellationToken)
     {
         if (User.GetUserId() is not { } userId || string.IsNullOrEmpty(userId))