Added swagger decoration, reorganized controller elements for better clarity, renamed entity index endpoint for better clarity

src/Client/Client.cs

@@ -108,7 +108,7 @@ public class Client
         public async Task<EntityIndexResult> EntityIndexAsync(string jsonEntity)
         {
             var content = new StringContent(jsonEntity, Encoding.UTF8, "application/json");
-            return await PutUrlAndProcessJson<EntityIndexResult>(GetUrl($"{baseUri}", "Entity", apiKey, []), content);
+            return await PutUrlAndProcessJson<EntityIndexResult>(GetUrl($"{baseUri}", "Entities", apiKey, []), content);
         }
 
         public async Task<EntityListResults> EntityListAsync(bool returnEmbeddings = false)

src/Server/Controllers/EntityController.cs

@@ -24,44 +24,17 @@ public class EntityController : ControllerBase
         _databaseHelper = databaseHelper;
     }
 
-    [HttpPut]
+    /// <summary>
-    public ActionResult<EntityIndexResult> Index([FromBody] List<JSONEntity>? jsonEntities)
+    /// List the entities in a searchdomain
-    {
+    /// </summary>
-        try
+    /// <remarks>
-        {
+    /// With returnModels = false expect: "Datapoints": [..., "Embeddings": null]<br/>
-            List<Entity>? entities = _searchdomainHelper.EntitiesFromJSON(
+    /// With returnModels = true expect: "Datapoints": [..., "Embeddings": [{"Model": "...", "Embeddings": []}, ...]]<br/>
-                _domainManager,
+    /// With returnEmbeddings = true expect: "Datapoints": [..., "Embeddings": [{"Model": "...", "Embeddings": [0.007384672,0.01309805,0.0012528514,...]}, ...]]
-                _logger,
+    /// </remarks>
-                JsonSerializer.Serialize(jsonEntities));
+    /// <param name="searchdomain">Name of the searchdomain</param>
-            if (entities is not null && jsonEntities is not null)
+    /// <param name="returnModels">Include the models in the response</param>
-            {
+    /// <param name="returnEmbeddings">Include the embeddings in the response (requires returnModels)</param>
-                List<string> invalidatedSearchdomains = [];
-                foreach (var jsonEntity in jsonEntities)
-                {
-                    string jsonEntityName = jsonEntity.Name;
-                    string jsonEntitySearchdomainName = jsonEntity.Searchdomain;
-                    if (entities.Select(x => x.name == jsonEntityName).Any()
-                        && !invalidatedSearchdomains.Contains(jsonEntitySearchdomainName))
-                    {
-                        invalidatedSearchdomains.Add(jsonEntitySearchdomainName);
-                    }
-                }
-                return Ok(new EntityIndexResult() { Success = true });
-            }
-            else
-            {
-                _logger.LogError("Unable to deserialize an entity");
-                return Ok(new EntityIndexResult() { Success = false, Message = "Unable to deserialize an entity"});
-            }
-        } catch (Exception ex)
-        {
-            if (ex.InnerException is not null) ex = ex.InnerException;
-            _logger.LogError("Unable to index the provided entities. {ex.Message} - {ex.StackTrace}", [ex.Message, ex.StackTrace]);
-            return Ok(new EntityIndexResult() { Success = false, Message = ex.Message });
-        }
-
-    }
-
     [HttpGet("/Entities")]
     public ActionResult<EntityListResults> List(string searchdomain, bool returnModels = false, bool returnEmbeddings = false)
     {
@@ -109,6 +82,56 @@ public class EntityController : ControllerBase
         return Ok(entityListResults);
     }
 
+    /// <summary>
+    /// Index entities
+    /// </summary>
+    /// <remarks>
+    /// Behavior: Creates new entities, but overwrites existing entities that have the same name
+    /// </remarks>
+    /// <param name="jsonEntities">Entities to index</param>
+    [HttpPut("/Entities")]
+    public ActionResult<EntityIndexResult> Index([FromBody] List<JSONEntity>? jsonEntities)
+    {
+        try
+        {
+            List<Entity>? entities = _searchdomainHelper.EntitiesFromJSON(
+                _domainManager,
+                _logger,
+                JsonSerializer.Serialize(jsonEntities));
+            if (entities is not null && jsonEntities is not null)
+            {
+                List<string> invalidatedSearchdomains = [];
+                foreach (var jsonEntity in jsonEntities)
+                {
+                    string jsonEntityName = jsonEntity.Name;
+                    string jsonEntitySearchdomainName = jsonEntity.Searchdomain;
+                    if (entities.Select(x => x.name == jsonEntityName).Any()
+                        && !invalidatedSearchdomains.Contains(jsonEntitySearchdomainName))
+                    {
+                        invalidatedSearchdomains.Add(jsonEntitySearchdomainName);
+                    }
+                }
+                return Ok(new EntityIndexResult() { Success = true });
+            }
+            else
+            {
+                _logger.LogError("Unable to deserialize an entity");
+                return Ok(new EntityIndexResult() { Success = false, Message = "Unable to deserialize an entity"});
+            }
+        } catch (Exception ex)
+        {
+            if (ex.InnerException is not null) ex = ex.InnerException;
+            _logger.LogError("Unable to index the provided entities. {ex.Message} - {ex.StackTrace}", [ex.Message, ex.StackTrace]);
+            return Ok(new EntityIndexResult() { Success = false, Message = ex.Message });
+        }
+
+    }
+
+    /// <summary>
+    /// Deletes an entity
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    /// <param name="entityName">Name of the entity</param>
     [HttpDelete]
     public ActionResult<EntityDeleteResults> Delete(string searchdomain, string entityName)
     {

src/Server/Controllers/SearchdomainController.cs

@@ -1,3 +1,4 @@
+using System.ComponentModel.DataAnnotations;
 using System.Text.Json;
 using ElmahCore;
 using Microsoft.AspNetCore.Http.HttpResults;
@@ -23,6 +24,9 @@ public class SearchdomainController : ControllerBase
         _domainManager = domainManager;
     }
 
+    /// <summary>
+    /// Lists all searchdomains
+    /// </summary>
     [HttpGet("/Searchdomains")]
     public ActionResult<SearchdomainListResults> List()
     {
@@ -40,8 +44,13 @@ public class SearchdomainController : ControllerBase
         return Ok(searchdomainListResults);
     }
 
+    /// <summary>
+    /// Creates a new searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    /// <param name="settings">Optional initial settings</param>
     [HttpPost]
-    public ActionResult<SearchdomainCreateResults> Create(string searchdomain, [FromBody]SearchdomainSettings settings = new())
+    public ActionResult<SearchdomainCreateResults> Create([Required]string searchdomain, [FromBody]SearchdomainSettings settings = new())
     {
         try
         {
@@ -54,8 +63,12 @@ public class SearchdomainController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Deletes a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
     [HttpDelete]
-    public ActionResult<SearchdomainDeleteResults> Delete(string searchdomain)
+    public ActionResult<SearchdomainDeleteResults> Delete([Required]string searchdomain)
     {
         bool success;
         int deletedEntries;
@@ -84,8 +97,14 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainDeleteResults(){Success = success, DeletedEntities = deletedEntries, Message = message});
     }
 
+    /// <summary>
+    /// Updates name and settings of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    /// <param name="newName">Updated name of the searchdomain</param>
+    /// <param name="settings">Updated settings of searchdomain</param>
     [HttpPut]
-    public ActionResult<SearchdomainUpdateResults> Update(string searchdomain, string newName, [FromBody]string? settings = "{}")
+    public ActionResult<SearchdomainUpdateResults> Update([Required]string searchdomain, string newName, [FromBody]SearchdomainSettings? settings)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -110,8 +129,29 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainUpdateResults(){Success = true});
     }
 
+    /// <summary>
+    /// Gets the query cache of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    [HttpGet("Queries")]
+    public ActionResult<SearchdomainSearchesResults> GetQueries([Required]string searchdomain)
+    {
+        (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
+        if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
+        Dictionary<string, DateTimedSearchResult> searchCache = searchdomain_.searchCache;
+        
+        return Ok(new SearchdomainSearchesResults() { Searches = searchCache, Success = true });
+    }
+
+    /// <summary>
+    /// Executes a query in the searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    /// <param name="query">Query to execute</param>
+    /// <param name="topN">Return only the top N results</param>
+    /// <param name="returnAttributes">Return the attributes of the object</param>
     [HttpPost("Query")]
-    public ActionResult<EntityQueryResults> Query(string searchdomain, string query, int? topN, bool returnAttributes = false)
+    public ActionResult<EntityQueryResults> Query([Required]string searchdomain, [Required]string query, int? topN, bool returnAttributes = false)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -125,33 +165,13 @@ public class SearchdomainController : ControllerBase
         return Ok(new EntityQueryResults(){Results = queryResults, Success = true });
     }
 
-    [HttpPut("Settings")]
+    /// <summary>
-    public ActionResult<SearchdomainUpdateResults> UpdateSettings(string searchdomain, [FromBody] SearchdomainSettings request)
+    /// Deletes a query from the query cache
-    {
+    /// </summary>
-        (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
+    /// <param name="searchdomain">Name of the searchdomain</param>
-        if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
+    /// <param name="query">Query to delete</param>
-        Dictionary<string, dynamic> parameters = new()
-        {
-            {"settings", JsonSerializer.Serialize(request)},
-            {"id", searchdomain_.id}
-        };
-        searchdomain_.helper.ExecuteSQLNonQuery("UPDATE searchdomain set settings = @settings WHERE id = @id", parameters);
-        searchdomain_.settings = request;
-        return Ok(new SearchdomainUpdateResults(){Success = true});
-    }
-
-    [HttpGet("Queries")]
-    public ActionResult<SearchdomainSearchesResults> GetQueries(string searchdomain)
-    {
-        (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
-        if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
-        Dictionary<string, DateTimedSearchResult> searchCache = searchdomain_.searchCache;
-        
-        return Ok(new SearchdomainSearchesResults() { Searches = searchCache, Success = true });
-    }
-
     [HttpDelete("Query")]
-    public ActionResult<SearchdomainDeleteSearchResult> DeleteQuery(string searchdomain, string query)
+    public ActionResult<SearchdomainDeleteSearchResult> DeleteQuery([Required]string searchdomain, [Required]string query)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -165,8 +185,14 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainDeleteSearchResult() {Success = false, Message = "Query not found in search cache"});
     }
 
+    /// <summary>
+    /// Updates a query from the query cache
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    /// <param name="query">Query to update</param>
+    /// <param name="results">List of results to apply to the query</param>
     [HttpPatch("Query")]
-    public ActionResult<SearchdomainUpdateSearchResult> UpdateQuery(string searchdomain, string query, [FromBody]List<ResultItem> results)
+    public ActionResult<SearchdomainUpdateSearchResult> UpdateQuery([Required]string searchdomain, [Required]string query, [Required][FromBody]List<ResultItem> results)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -182,8 +208,12 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainUpdateSearchResult() {Success = false, Message = "Query not found in search cache"});
     }
 
+    /// <summary>
+    /// Get the settings of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
     [HttpGet("Settings")]
-    public ActionResult<SearchdomainSettingsResults> GetSettings(string searchdomain)
+    public ActionResult<SearchdomainSettingsResults> GetSettings([Required]string searchdomain)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -191,8 +221,31 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainSettingsResults() { Settings = settings, Success = true });
     }
 
+    /// <summary>
+    /// Update the settings of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
+    [HttpPut("Settings")]
+    public ActionResult<SearchdomainUpdateResults> UpdateSettings([Required]string searchdomain, [Required][FromBody] SearchdomainSettings request)
+    {
+        (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
+        if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
+        Dictionary<string, dynamic> parameters = new()
+        {
+            {"settings", JsonSerializer.Serialize(request)},
+            {"id", searchdomain_.id}
+        };
+        searchdomain_.helper.ExecuteSQLNonQuery("UPDATE searchdomain set settings = @settings WHERE id = @id", parameters);
+        searchdomain_.settings = request;
+        return Ok(new SearchdomainUpdateResults(){Success = true});
+    }
+
+    /// <summary>
+    /// Get the query cache size of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
     [HttpGet("SearchCache/Size")]
-    public ActionResult<SearchdomainSearchCacheSizeResults> GetSearchCacheSize(string searchdomain)
+    public ActionResult<SearchdomainSearchCacheSizeResults> GetSearchCacheSize([Required]string searchdomain)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -207,8 +260,12 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainSearchCacheSizeResults() { SearchCacheSizeBytes = sizeInBytes, Success = true });
     }
 
+    /// <summary>
+    /// Clear the query cache of a searchdomain
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
     [HttpPost("SearchCache/Clear")]
-    public ActionResult<SearchdomainInvalidateCacheResults> InvalidateSearchCache(string searchdomain)
+    public ActionResult<SearchdomainInvalidateCacheResults> InvalidateSearchCache([Required]string searchdomain)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});
@@ -216,8 +273,12 @@ public class SearchdomainController : ControllerBase
         return Ok(new SearchdomainInvalidateCacheResults(){Success = true});
     }
 
+    /// <summary>
+    /// Get the disk size of a searchdomain in bytes
+    /// </summary>
+    /// <param name="searchdomain">Name of the searchdomain</param>
     [HttpGet("Database/Size")]
-    public ActionResult<SearchdomainGetDatabaseSizeResult> GetDatabaseSize(string searchdomain)
+    public ActionResult<SearchdomainGetDatabaseSizeResult> GetDatabaseSize([Required]string searchdomain)
     {
         (Searchdomain? searchdomain_, int? httpStatusCode, string? message) = SearchdomainHelper.TryGetSearchdomain(_domainManager, searchdomain, _logger);
         if (searchdomain_ is null || httpStatusCode is not null) return StatusCode(httpStatusCode ?? 500, new SearchdomainUpdateResults(){Success = false, Message = message});

src/Server/Controllers/ServerController.cs

@@ -22,6 +22,12 @@ public class ServerController : ControllerBase
         _aIProvider = aIProvider;
     }
 
+    /// <summary>
+    /// Lists the models available to the server
+    /// </summary>
+    /// <remarks>
+    /// Returns ALL models available to the server - not only the embedding models.
+    /// </remarks>
     [HttpGet("Models")]
     public ActionResult<ServerGetModelsResult> GetModels()
     {

src/Server/Program.cs

@@ -9,6 +9,7 @@ using Server.Helper;
 using Server.Models;
 using Server.Services;
 using System.Text.Json.Serialization;
+using System.Reflection;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -37,7 +38,12 @@ builder.Services.AddScoped<LocalizationService>();
 
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+builder.Services.AddSwaggerGen(c =>
+{
+    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+    c.IncludeXmlComments(xmlPath);
+});
 Log.Logger = new LoggerConfiguration()
     .ReadFrom.Configuration(builder.Configuration)
     .CreateLogger();

src/Server/Server.csproj

@@ -6,6 +6,11 @@
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="AdaptiveExpressions" Version="4.23.0" />
     <PackageReference Include="ElmahCore" Version="2.1.2" />

src/Server/Views/Home/Index.cshtml

@@ -745,7 +745,7 @@
                   "datapoints": datapoints
                 }];
                 showToast("@T["Creating entity"]", "primary");
-                fetch(`/Entity`, {
+                fetch(`/Entities`, {
                     method: 'PUT',
                     headers: {
                         'Content-Type': 'application/json'
@@ -874,7 +874,7 @@
                   "datapoints": datapoints
                 }];
                 showToast("@T["Updating entity"]", "primary");
-                fetch(`/Entity`, {
+                fetch(`/Entities`, {
                     method: 'PUT',
                     headers: {
                         'Content-Type': 'application/json'