From 04d5d466bb67dd02241a43cc362e7a0e054fb5b0 Mon Sep 17 00:00:00 2001
From: Sebastian <sebastian@squidex.io>
Date: Wed, 7 Sep 2022 14:36:15 +0200
Subject: [PATCH] Add more controllers to OpenApi.

---
 .../Controllers/Apps/AppAssetsController.cs   |  2 +-
 .../Controllers/Apps/AppClientsController.cs  |  2 +-
 .../Apps/AppContributorsController.cs         |  4 +-
 .../Controllers/Apps/AppImageController.cs    |  2 +-
 .../Apps/AppLanguagesController.cs            |  2 +-
 .../Controllers/Apps/AppRolesController.cs    |  2 +-
 .../Controllers/Apps/AppSettingsController.cs |  2 +-
 .../Apps/AppWorkflowsController.cs            |  2 +-
 .../Api/Controllers/Apps/AppsController.cs    |  2 +-
 .../Assets/AssetFoldersController.cs          |  2 +-
 .../Controllers/Assets/AssetsController.cs    |  4 +-
 .../Backups/BackupContentController.cs        |  2 +-
 .../Controllers/Backups/BackupsController.cs  |  2 +-
 .../Controllers/Backups/RestoreController.cs  |  2 +-
 .../Comments/CommentsController.cs            |  2 +-
 .../UserNotificationsController.cs            |  2 +-
 .../Contents/ContentsController.cs            |  2 +-
 .../EventConsumersController.cs               | 34 ++++++++
 .../EventConsumers/Models/EventConsumerDto.cs | 20 +++++
 .../Controllers/Plans/AppPlansController.cs   |  2 +-
 .../Api/Controllers/Rules/RulesController.cs  |  2 +-
 .../Schemas/SchemaFieldsController.cs         |  2 +-
 .../Controllers/Schemas/SchemasController.cs  |  2 +-
 .../Controllers/Users/Models/ResourcesDto.cs  | 10 +--
 .../Users/UserManagementController.cs         | 78 +++++++++++++++++--
 .../Api/Controllers/Users/UsersController.cs  |  2 +-
 26 files changed, 155 insertions(+), 35 deletions(-)

diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppAssetsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppAssetsController.cs
index b6d3745aa..7448c381a 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppAssetsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppAssetsController.cs
@@ -15,7 +15,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppAssetsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppClientsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppClientsController.cs
index 3482510de..781ef6349 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppClientsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppClientsController.cs
@@ -17,7 +17,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppClientsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppContributorsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppContributorsController.cs
index 2dd8665eb..bc27eaa9f 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppContributorsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppContributorsController.cs
@@ -23,7 +23,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppContributorsController : ApiController
@@ -76,7 +76,7 @@ namespace Squidex.Areas.Api.Controllers.Apps
         /// </returns>
         [HttpPost]
         [Route("apps/{app}/contributors/")]
-        [ProducesResponseType(typeof(ContributorsDto), 201)]
+        [ProducesResponseType(typeof(ContributorsDto), StatusCodes.Status201Created)]
         [ApiPermissionOrAnonymous(PermissionIds.AppContributorsAssign)]
         [ApiCosts(1)]
         public async Task<IActionResult> PostContributor(string app, [FromBody] AssignContributorDto request)
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppImageController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppImageController.cs
index 4faf0a48a..825f20cf9 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppImageController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppImageController.cs
@@ -17,7 +17,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppImageController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppLanguagesController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppLanguagesController.cs
index 98eb8cd18..0c0303648 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppLanguagesController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppLanguagesController.cs
@@ -18,7 +18,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppLanguagesController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppRolesController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppRolesController.cs
index 91edfd15b..d1fefd7fc 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppRolesController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppRolesController.cs
@@ -18,7 +18,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppRolesController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppSettingsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppSettingsController.cs
index 832a55fc6..df0603a92 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppSettingsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppSettingsController.cs
@@ -15,7 +15,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppSettingsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppWorkflowsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppWorkflowsController.cs
index 2f14346b3..d51c40c78 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppWorkflowsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppWorkflowsController.cs
@@ -19,7 +19,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppWorkflowsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppsController.cs
index 0d9cfe971..97f666614 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Apps/AppsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Apps/AppsController.cs
@@ -21,7 +21,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Apps
 {
     /// <summary>
-    /// Manages and configures apps.
+    /// Update and query apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Apps))]
     public sealed class AppsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetFoldersController.cs b/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetFoldersController.cs
index 5e5f95ed2..ac9317383 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetFoldersController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetFoldersController.cs
@@ -79,7 +79,7 @@ namespace Squidex.Areas.Api.Controllers.Assets
         /// </returns>
         [HttpPost]
         [Route("apps/{app}/assets/folders", Order = -1)]
-        [ProducesResponseType(typeof(AssetFolderDto), 201)]
+        [ProducesResponseType(typeof(AssetFolderDto), StatusCodes.Status201Created)]
         [AssetRequestSizeLimit]
         [ApiPermissionOrAnonymous(PermissionIds.AppAssetsUpdate)]
         [ApiCosts(1)]
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetsController.cs
index b17c24fc2..2f0c62617 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Assets/AssetsController.cs
@@ -208,7 +208,7 @@ namespace Squidex.Areas.Api.Controllers.Assets
         /// </remarks>
         [HttpPost]
         [Route("apps/{app}/assets/")]
-        [ProducesResponseType(typeof(AssetDto), 201)]
+        [ProducesResponseType(typeof(AssetDto), StatusCodes.Status201Created)]
         [AssetRequestSizeLimit]
         [ApiPermissionOrAnonymous(PermissionIds.AppAssetsCreate)]
         [ApiCosts(1)]
@@ -236,7 +236,7 @@ namespace Squidex.Areas.Api.Controllers.Assets
         /// </remarks>
         [OpenApiIgnore]
         [Route("apps/{app}/assets/tus/{**fileId}")]
-        [ProducesResponseType(typeof(AssetDto), 201)]
+        [ProducesResponseType(typeof(AssetDto), StatusCodes.Status201Created)]
         [AssetRequestSizeLimit]
         [ApiPermissionOrAnonymous(PermissionIds.AppAssetsCreate)]
         [ApiCosts(1)]
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupContentController.cs b/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupContentController.cs
index 3d10533ef..9be09dd94 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupContentController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupContentController.cs
@@ -15,7 +15,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Backups
 {
     /// <summary>
-    /// Manages backups for app.
+    /// Update and query backups for app.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Backups))]
     public class BackupContentController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupsController.cs
index 7c94d559a..27ca1a44c 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Backups/BackupsController.cs
@@ -17,7 +17,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Backups
 {
     /// <summary>
-    /// Manages backups for apps.
+    /// Update and query backups for apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Backups))]
     public class BackupsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Backups/RestoreController.cs b/backend/src/Squidex/Areas/Api/Controllers/Backups/RestoreController.cs
index 53f5c7056..779badd41 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Backups/RestoreController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Backups/RestoreController.cs
@@ -16,7 +16,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Backups
 {
     /// <summary>
-    /// Manages backups for apps.
+    /// Update and query backups for apps.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Backups))]
     [ApiModelValidation(true)]
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Comments/CommentsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Comments/CommentsController.cs
index 492b0e215..bedc8ece7 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Comments/CommentsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Comments/CommentsController.cs
@@ -21,7 +21,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Comments
 {
     /// <summary>
-    /// Manages comments for any kind of app resource.
+    /// Update and query comments for any kind of app resource.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Comments))]
     public sealed class CommentsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Comments/Notifications/UserNotificationsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Comments/Notifications/UserNotificationsController.cs
index e92789a79..548fecc35 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Comments/Notifications/UserNotificationsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Comments/Notifications/UserNotificationsController.cs
@@ -20,7 +20,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Comments.Notifications
 {
     /// <summary>
-    /// Manages user notifications.
+    /// Update and query user notifications.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Notifications))]
     public sealed class UserNotificationsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Contents/ContentsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Contents/ContentsController.cs
index e309bf7ea..1c8553ea7 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Contents/ContentsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Contents/ContentsController.cs
@@ -351,7 +351,7 @@ namespace Squidex.Areas.Api.Controllers.Contents
         /// </remarks>
         [HttpPost]
         [Route("content/{app}/{schema}/")]
-        [ProducesResponseType(typeof(ContentsDto), 201)]
+        [ProducesResponseType(typeof(ContentsDto), StatusCodes.Status201Created)]
         [ApiPermissionOrAnonymous(PermissionIds.AppContentsCreate)]
         [ApiCosts(1)]
         public async Task<IActionResult> PostContent(string app, string schema, CreateContentDto request)
diff --git a/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/EventConsumersController.cs b/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/EventConsumersController.cs
index 2511bf03a..ee2080223 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/EventConsumersController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/EventConsumersController.cs
@@ -14,6 +14,10 @@ using Squidex.Web;
 
 namespace Squidex.Areas.Api.Controllers.EventConsumers
 {
+    /// <summary>
+    /// Update and query event consumers.
+    /// </summary>
+    [ApiExplorerSettings(GroupName = nameof(EventConsumers))]
     public sealed class EventConsumersController : ApiController
     {
         private readonly IEventConsumerManager eventConsumerManager;
@@ -24,6 +28,12 @@ namespace Squidex.Areas.Api.Controllers.EventConsumers
             this.eventConsumerManager = eventConsumerManager;
         }
 
+        /// <summary>
+        /// Get event consumers.
+        /// </summary>
+        /// <returns>
+        /// 200 => Event consumers returned.
+        /// </returns>
         [HttpGet]
         [Route("event-consumers/")]
         [ProducesResponseType(typeof(EventConsumersDto), StatusCodes.Status200OK)]
@@ -37,6 +47,14 @@ namespace Squidex.Areas.Api.Controllers.EventConsumers
             return Ok(response);
         }
 
+        /// <summary>
+        /// Start an event consumer.
+        /// </summary>
+        /// <param name="consumerName">The name of the event consumer.</param>
+        /// <returns>
+        /// 200 => Event consumer started asynchronously.
+        /// 404 => Event consumer not found.
+        /// </returns>
         [HttpPut]
         [Route("event-consumers/{consumerName}/start/")]
         [ProducesResponseType(typeof(EventConsumerDto), StatusCodes.Status200OK)]
@@ -50,6 +68,14 @@ namespace Squidex.Areas.Api.Controllers.EventConsumers
             return Ok(response);
         }
 
+        /// <summary>
+        /// Stop an event consumer.
+        /// </summary>
+        /// <param name="consumerName">The name of the event consumer.</param>
+        /// <returns>
+        /// 200 => Event consumer stopped asynchronously.
+        /// 404 => Event consumer not found.
+        /// </returns>
         [HttpPut]
         [Route("event-consumers/{consumerName}/stop/")]
         [ProducesResponseType(typeof(EventConsumerDto), StatusCodes.Status200OK)]
@@ -63,6 +89,14 @@ namespace Squidex.Areas.Api.Controllers.EventConsumers
             return Ok(response);
         }
 
+        /// <summary>
+        /// Reset an event consumer.
+        /// </summary>
+        /// <param name="consumerName">The name of the event consumer.</param>
+        /// <returns>
+        /// 200 => Event consumer resetted asynchronously.
+        /// 404 => Event consumer not found.
+        /// </returns>
         [HttpPut]
         [Route("event-consumers/{consumerName}/reset/")]
         [ProducesResponseType(typeof(EventConsumerDto), StatusCodes.Status200OK)]
diff --git a/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/Models/EventConsumerDto.cs b/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/Models/EventConsumerDto.cs
index da253b0f5..05db4eb50 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/Models/EventConsumerDto.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/EventConsumers/Models/EventConsumerDto.cs
@@ -7,22 +7,42 @@
 
 using Squidex.Infrastructure.EventSourcing;
 using Squidex.Infrastructure.Reflection;
+using Squidex.Infrastructure.Validation;
 using Squidex.Web;
 
 namespace Squidex.Areas.Api.Controllers.EventConsumers.Models
 {
     public sealed class EventConsumerDto : Resource
     {
+        /// <summary>
+        /// Indicates if the event consumer has been started.
+        /// </summary>
         public bool IsStopped { get; set; }
 
+        /// <summary>
+        /// Indicates if the event consumer is resetting at the moment.
+        /// </summary>
         public bool IsResetting { get; set; }
 
+        /// <summary>
+        /// The number of handled events.
+        /// </summary>
         public int Count { get; set; }
 
+        /// <summary>
+        /// The name of the event consumer.
+        /// </summary>
+        [LocalizedRequired]
         public string Name { get; set; }
 
+        /// <summary>
+        /// The error details if the event consumer has been stopped after a failure.
+        /// </summary>
         public string? Error { get; set; }
 
+        /// <summary>
+        /// The position within the vent stream.
+        /// </summary>
         public string? Position { get; set; }
 
         public static EventConsumerDto FromDomain(EventConsumerInfo eventConsumerInfo, Resources resources)
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Plans/AppPlansController.cs b/backend/src/Squidex/Areas/Api/Controllers/Plans/AppPlansController.cs
index a9707fa67..2e6510122 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Plans/AppPlansController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Plans/AppPlansController.cs
@@ -16,7 +16,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Plans
 {
     /// <summary>
-    /// Manages and configures plans.
+    /// Update and query plans.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Plans))]
     public sealed class AppPlansController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Rules/RulesController.cs b/backend/src/Squidex/Areas/Api/Controllers/Rules/RulesController.cs
index 1a9d37c82..488b6f153 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Rules/RulesController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Rules/RulesController.cs
@@ -27,7 +27,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Rules
 {
     /// <summary>
-    /// Manages and retrieves information about rules.
+    /// Update and query information about rules.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Rules))]
     public sealed class RulesController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemaFieldsController.cs b/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemaFieldsController.cs
index 1d5296b47..c613f1562 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemaFieldsController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemaFieldsController.cs
@@ -16,7 +16,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Schemas
 {
     /// <summary>
-    /// Manages and retrieves information about schemas.
+    /// Update and query information about schemas.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Schemas))]
     public sealed class SchemaFieldsController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemasController.cs b/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemasController.cs
index f9962e002..440556373 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemasController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Schemas/SchemasController.cs
@@ -24,7 +24,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Schemas
 {
     /// <summary>
-    /// Manages and retrieves information about schemas.
+    /// Update and query information about schemas.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Schemas))]
     public sealed class SchemasController : ApiController
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Users/Models/ResourcesDto.cs b/backend/src/Squidex/Areas/Api/Controllers/Users/Models/ResourcesDto.cs
index 03a0db791..6a9e2ccfd 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Users/Models/ResourcesDto.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Users/Models/ResourcesDto.cs
@@ -20,28 +20,28 @@ namespace Squidex.Areas.Api.Controllers.Users.Models
             var result = new ResourcesDto();
 
             result.AddGetLink("ping",
-    resources.Url<PingController>(x => nameof(x.GetPing)));
+                resources.Url<PingController>(x => nameof(x.GetPing)));
 
             if (resources.CanReadEvents)
             {
                 result.AddGetLink("admin/events",
-    resources.Url<EventConsumersController>(x => nameof(x.GetEventConsumers)));
+                    resources.Url<EventConsumersController>(x => nameof(x.GetEventConsumers)));
             }
 
             if (resources.CanRestoreBackup)
             {
                 result.AddGetLink("admin/restore",
-    resources.Url<RestoreController>(x => nameof(x.GetRestoreJob)));
+                    resources.Url<RestoreController>(x => nameof(x.GetRestoreJob)));
             }
 
             if (resources.CanReadUsers)
             {
                 result.AddGetLink("admin/users",
-    resources.Url<UserManagementController>(x => nameof(x.GetUsers)));
+                    resources.Url<UserManagementController>(x => nameof(x.GetUsers)));
             }
 
             result.AddGetLink("languages",
-    resources.Url<LanguagesController>(x => nameof(x.GetLanguages)));
+                resources.Url<LanguagesController>(x => nameof(x.GetLanguages)));
 
             return result;
         }
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Users/UserManagementController.cs b/backend/src/Squidex/Areas/Api/Controllers/Users/UserManagementController.cs
index dc055cc60..dff46d148 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Users/UserManagementController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Users/UserManagementController.cs
@@ -16,7 +16,11 @@ using Squidex.Web;
 
 namespace Squidex.Areas.Api.Controllers.Users
 {
+    /// <summary>
+    /// Retrieve and manage users.
+    /// </summary>
     [ApiModelValidation(true)]
+    [ApiExplorerSettings(GroupName = "UserManagement")]
     public sealed class UserManagementController : ApiController
     {
         private readonly IUserService userService;
@@ -27,6 +31,15 @@ namespace Squidex.Areas.Api.Controllers.Users
             this.userService = userService;
         }
 
+        /// <summary>
+        /// Get users by query.
+        /// </summary>
+        /// <param name="query">Optional query to search by email address or username.</param>
+        /// <param name="skip">The number of users to skip.</param>
+        /// <param name="take">The number of users to return.</param>
+        /// <returns>
+        /// 200 => Users returned.
+        /// </returns>
         [HttpGet]
         [Route("user-management/")]
         [ProducesResponseType(typeof(UsersDto), StatusCodes.Status200OK)]
@@ -40,9 +53,17 @@ namespace Squidex.Areas.Api.Controllers.Users
             return Ok(response);
         }
 
+        /// <summary>
+        /// Get a user by ID.
+        /// </summary>
+        /// <param name="id">The ID of the user.</param>
+        /// <returns>
+        /// 200 => User returned.
+        /// 404 => User not found.
+        /// </returns>
         [HttpGet]
         [Route("user-management/{id}/")]
-        [ProducesResponseType(typeof(UserDto), 201)]
+        [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
         [ApiPermission(PermissionIds.AdminUsersRead)]
         public async Task<IActionResult> GetUser(string id)
         {
@@ -58,9 +79,17 @@ namespace Squidex.Areas.Api.Controllers.Users
             return Ok(response);
         }
 
+        /// <summary>
+        /// Create a new user.
+        /// </summary>
+        /// <param name="request">The user object that needs to be added.</param>
+        /// <returns>
+        /// 201 => User created.
+        /// 400 => User request not valid.
+        /// </returns>
         [HttpPost]
         [Route("user-management/")]
-        [ProducesResponseType(typeof(UserDto), 201)]
+        [ProducesResponseType(typeof(UserDto), StatusCodes.Status201Created)]
         [ApiPermission(PermissionIds.AdminUsersCreate)]
         public async Task<IActionResult> PostUser([FromBody] CreateUserDto request)
         {
@@ -68,12 +97,22 @@ namespace Squidex.Areas.Api.Controllers.Users
 
             var response = UserDto.FromDomain(user, Resources);
 
-            return Ok(response);
+            return CreatedAtAction(nameof(GetUser), new { id = user.Id }, response);
         }
 
+        /// <summary>
+        /// Update a user.
+        /// </summary>
+        /// <param name="id">The ID of the user.</param>
+        /// <param name="request">The user object that needs to be updated.</param>
+        /// <returns>
+        /// 200 => User created.
+        /// 400 => User request not valid.
+        /// 404 => User not found.
+        /// </returns>
         [HttpPut]
         [Route("user-management/{id}/")]
-        [ProducesResponseType(typeof(UserDto), 201)]
+        [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
         [ApiPermission(PermissionIds.AdminUsersUpdate)]
         public async Task<IActionResult> PutUser(string id, [FromBody] UpdateUserDto request)
         {
@@ -84,9 +123,18 @@ namespace Squidex.Areas.Api.Controllers.Users
             return Ok(response);
         }
 
+        /// <summary>
+        /// Lock a user.
+        /// </summary>
+        /// <param name="id">The ID of the user to lock.</param>
+        /// <returns>
+        /// 200 => User locked.
+        /// 403 => User is the current user.
+        /// 404 => User not found.
+        /// </returns>
         [HttpPut]
         [Route("user-management/{id}/lock/")]
-        [ProducesResponseType(typeof(UserDto), 201)]
+        [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
         [ApiPermission(PermissionIds.AdminUsersLock)]
         public async Task<IActionResult> LockUser(string id)
         {
@@ -102,9 +150,18 @@ namespace Squidex.Areas.Api.Controllers.Users
             return Ok(response);
         }
 
+        /// <summary>
+        /// Unlock a user.
+        /// </summary>
+        /// <param name="id">The ID of the user to unlock.</param>
+        /// <returns>
+        /// 200 => User unlocked.
+        /// 403 => User is the current user.
+        /// 404 => User not found.
+        /// </returns>
         [HttpPut]
         [Route("user-management/{id}/unlock/")]
-        [ProducesResponseType(typeof(UserDto), 201)]
+        [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
         [ApiPermission(PermissionIds.AdminUsersUnlock)]
         public async Task<IActionResult> UnlockUser(string id)
         {
@@ -120,6 +177,15 @@ namespace Squidex.Areas.Api.Controllers.Users
             return Ok(response);
         }
 
+        /// <summary>
+        /// Delete a User.
+        /// </summary>
+        /// <param name="id">The ID of the user to delete.</param>
+        /// <returns>
+        /// 204 => User deleted.
+        /// 403 => User is the current user.
+        /// 404 => User not found.
+        /// </returns>
         [HttpDelete]
         [Route("user-management/{id}/")]
         [ProducesResponseType(StatusCodes.Status204NoContent)]
diff --git a/backend/src/Squidex/Areas/Api/Controllers/Users/UsersController.cs b/backend/src/Squidex/Areas/Api/Controllers/Users/UsersController.cs
index 13640c40a..48842195a 100644
--- a/backend/src/Squidex/Areas/Api/Controllers/Users/UsersController.cs
+++ b/backend/src/Squidex/Areas/Api/Controllers/Users/UsersController.cs
@@ -17,7 +17,7 @@ using Squidex.Web;
 namespace Squidex.Areas.Api.Controllers.Users
 {
     /// <summary>
-    /// Readonly API to retrieve information about squidex users.
+    /// Update and query users.
     /// </summary>
     [ApiExplorerSettings(GroupName = nameof(Users))]
     public sealed class UsersController : ApiController