PR feedback and Swagger docs updates

acoumb · acoumb · commit 7d1fe9caa57d · 2024-06-11T13:20:01.000+03:00
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/AlgoliaComposer.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/AlgoliaComposer.cs
@@ -1,6 +1,7 @@
 ﻿using Algolia.Search.Models.Search;
 using Microsoft.Extensions.DependencyInjection;
-
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
 using Umbraco.Cms.Core.Composing;
 using Umbraco.Cms.Core.DependencyInjection;
 using Umbraco.Cms.Core.Notifications;
@@ -37,6 +38,19 @@ public void Compose(IUmbracoBuilder builder)
             builder.Services.AddScoped<IAlgoliaSearchPropertyIndexValueFactory, AlgoliaSearchPropertyIndexValueFactory>();
 
             builder.AddAlgoliaConverters();
+
+            // Generate Swagger documentation for Algolia Search API
+            builder.Services.Configure<SwaggerGenOptions>(options =>
+            {
+                options.SwaggerDoc(
+                    Constants.ManagementApi.GroupName,
+                    new OpenApiInfo
+                    {
+                        Title = Constants.ManagementApi.ApiTitle,
+                        Version = "Latest",
+                        Description = $"Describes the {Constants.ManagementApi.ApiTitle} available for handling indices."
+                    });
+            });
         }
 
     }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/BuildIndexController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/BuildIndexController.cs
@@ -1,4 +1,5 @@
 ﻿using Algolia.Search.Models.Search;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using System.Text.Json;
@@ -13,6 +14,7 @@
 
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
+    [ApiVersion("1.0")]
     public class BuildIndexController : SearchControllerBase
     {
         public BuildIndexController(
@@ -69,11 +71,12 @@ public async Task<IActionResult> BuildIndex([FromBody] IndexConfiguration indexC
 
                 var result = await IndexService.PushData(index.Name, payload);
 
-                return new JsonResult(result);
+                return Ok(result);
             }
             catch (Exception ex)
             {
-                return new JsonResult(Result.Fail(ex.Message));
+                Logger.LogError(ex, ex.Message);
+                throw;
             }
         }
     }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/DeleteIndexController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/DeleteIndexController.cs
@@ -1,4 +1,5 @@
 ﻿using Algolia.Search.Models.Search;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using Umbraco.Cms.Core.Routing;
@@ -11,6 +12,7 @@
 
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
+    [ApiVersion("1.0")]
     public class DeleteIndexController : SearchControllerBase
     {
         public DeleteIndexController(
@@ -47,11 +49,12 @@ public async Task<IActionResult> DeleteIndex(int id)
 
                 await IndexService.DeleteIndex(indexName);
 
-                return new JsonResult(Result.Ok());
+                return Ok(Result.Ok());
             }
             catch (Exception ex)
             {
-                return new JsonResult(Result.Fail(ex.Message));
+                Logger.LogError(ex, ex.Message);
+                throw;
             }
         }
 
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetContentTypesController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetContentTypesController.cs
@@ -17,7 +17,6 @@
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
     [ApiVersion("1.0")]
-    [ApiExplorerSettings(GroupName = Constants.ManagementApi.GroupName)]
     public class GetContentTypesController : SearchControllerBase
     {
         private readonly IContentTypeService _contentTypeService;
@@ -106,7 +105,7 @@ public IActionResult GetContentTypes(int? id)
                 });
             }
 
-            return new JsonResult(list);    
+            return Ok(list);    
         }
 
     }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetIndexByIdController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetIndexByIdController.cs
@@ -1,4 +1,5 @@
 ﻿using Algolia.Search.Models.Search;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using System.Text.Json;
@@ -13,6 +14,7 @@
 
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
+    [ApiVersion("1.0")]
     public class GetIndexByIdController : SearchControllerBase
     {
         public GetIndexByIdController(
@@ -51,7 +53,7 @@ public IActionResult GetIndexById(int id)
                 ContentData = JsonSerializer.Deserialize<IEnumerable<ContentTypeDto>>(index.SerializedData)
             };
 
-            return new JsonResult(indexConfiguration);
+            return Ok(indexConfiguration);
         }
     }
 }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetIndicesController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/GetIndicesController.cs
@@ -17,7 +17,6 @@
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
     [ApiVersion("1.0")]
-    [ApiExplorerSettings(GroupName = Constants.ManagementApi.GroupName)]
     public class GetIndicesController : SearchControllerBase
     {
         public GetIndicesController(
@@ -46,14 +45,16 @@ public GetIndicesController(
 
         [HttpGet("index")]
         [ProducesResponseType(typeof(IEnumerable<IndexConfiguration>), StatusCodes.Status200OK)]
-        public IEnumerable<IndexConfiguration> GetIndices()
+        public IActionResult GetIndices()
         {
-            return IndexStorage.Get().Select(p => new IndexConfiguration
+            var indices = IndexStorage.Get().Select(p => new IndexConfiguration
             {
                 Id = p.Id,
                 Name = p.Name,
                 ContentData = JsonSerializer.Deserialize<IEnumerable<ContentTypeDto>>(p.SerializedData)
             });
+
+            return Ok(indices);
         }
     }
 }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SaveIndexController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SaveIndexController.cs
@@ -1,4 +1,5 @@
 ﻿using Algolia.Search.Models.Search;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using System.Text.Json;
@@ -12,6 +13,7 @@
 
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
+    [ApiVersion("1.0")]
     public class SaveIndexController : SearchControllerBase
     {
         public SaveIndexController(
@@ -56,11 +58,12 @@ public async Task<IActionResult> SaveIndex([FromBody] IndexConfiguration index)
                     ? Result.Ok()
                     : await IndexService.PushData(index.Name);
 
-                return new JsonResult(result);
+                return Ok(result);
             }
             catch (Exception ex)
             {
-                return new JsonResult(Result.Fail(ex.Message));
+                Logger.LogError(ex, ex.Message);
+                throw;
             }
         }
     }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SearchControllerBase.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SearchControllerBase.cs
@@ -20,7 +20,7 @@ namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
     [BackOfficeRoute($"{Constants.ManagementApi.RootPath}/v{{version:apiVersion}}/search")]
     [Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)]
     [MapToApi(Constants.ManagementApi.GroupName)]
-    public abstract class SearchControllerBase 
+    public abstract class SearchControllerBase : Controller
     {
         protected IAlgoliaIndexService IndexService { get; }
 
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SearchIndexController.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/SearchIndexController.cs
@@ -1,4 +1,5 @@
 ﻿using Algolia.Search.Models.Search;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using Umbraco.Cms.Core.Routing;
@@ -11,6 +12,7 @@
 
 namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers
 {
+    [ApiVersion("1.0")]
     public class SearchIndexController : SearchControllerBase
     {
         public SearchIndexController(
@@ -51,7 +53,7 @@ public IActionResult Search(int indexId, string query)
                 Hits = searchResults.Hits.Select(p => p.Data.ToDictionary(x => x.Key, y => y.Value.ToString())).ToList()
             };
 
-            return new JsonResult(response);
+            return Ok(response);
         }
     }
 }
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/TimeDashboardControllerBase.cs b/src/Umbraco.Cms.Integrations.Search.Algolia/Api/Management/Controllers/TimeDashboardControllerBase.cs
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Client/package.json b/src/Umbraco.Cms.Integrations.Search.Algolia/Client/package.json
@@ -3,15 +3,22 @@
   "private": true,
   "version": "0.0.0",
   "type": "module",
+  "engines": {
+    "node": ">=20.9 <21",
+    "npm": ">=10.1 < 11"
+  },
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "watch": "vite build --watch",
+    "generate:api": "openapi-ts --input https://localhost:44340/umbraco/swagger/AlgoliaSearch/swagger.json --output src/generated --debug true --enums typescript --lint true --schemas false"
   },
   "dependencies": {
     "lit": "^3.1.2"
   },
   "devDependencies": {
+    "@hey-api/openapi-ts": "^0.37.3",
     "@umbraco-cms/backoffice": "^14.0.0",
     "eslint": "^9.4.0",
     "typescript": "^5.2.2",
diff --git a/src/Umbraco.Cms.Integrations.Search.Algolia/Client/public/umbraco-package.json b/src/Umbraco.Cms.Integrations.Search.Algolia/Client/public/umbraco-package.json
@@ -1,5 +1,6 @@
 ﻿{
-  "name": "Umbraco.Cms.Integrations.Search.Algolia",
+  "id": "Umbraco.Cms.Integrations.Search.Algolia",
+  "name": "Umbraco CMS Integrations: Search - Algolia",
   "version": "3.0.0",
   "extensions": [
     {

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`using Algolia.Search.Models.Search;`
	`2`	`+using Asp.Versioning;`
`2`	`3`	`using Microsoft.AspNetCore.Mvc;`
`3`	`4`	`using Microsoft.Extensions.Logging;`
`4`	`5`	`using System.Text.Json;`
`@@ -13,6 +14,7 @@`
`13`	`14`
`14`	`15`	`namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers`
`15`	`16`	`{`
	`17`	`+ [ApiVersion("1.0")]`
`16`	`18`	`public class BuildIndexController : SearchControllerBase`
`17`	`19`	`{`
`18`	`20`	`public BuildIndexController(`
`@@ -69,11 +71,12 @@ public async Task<IActionResult> BuildIndex([FromBody] IndexConfiguration indexC`
`69`	`71`
`70`	`72`	`var result = await IndexService.PushData(index.Name, payload);`
`71`	`73`
`72`		`- return new JsonResult(result);`
	`74`	`+ return Ok(result);`
`73`	`75`	`}`
`74`	`76`	`catch (Exception ex)`
`75`	`77`	`{`
`76`		`- return new JsonResult(Result.Fail(ex.Message));`
	`78`	`+ Logger.LogError(ex, ex.Message);`
	`79`	`+ throw;`
`77`	`80`	`}`
`78`	`81`	`}`
`79`	`82`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,6 @@`
`17`	`17`	`namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers`
`18`	`18`	`{`
`19`	`19`	`[ApiVersion("1.0")]`
`20`		`- [ApiExplorerSettings(GroupName = Constants.ManagementApi.GroupName)]`
`21`	`20`	`public class GetContentTypesController : SearchControllerBase`
`22`	`21`	`{`
`23`	`22`	`private readonly IContentTypeService _contentTypeService;`
`@@ -106,7 +105,7 @@ public IActionResult GetContentTypes(int? id)`
`106`	`105`	`});`
`107`	`106`	`}`
`108`	`107`
`109`		`- return new JsonResult(list);`
	`108`	`+ return Ok(list);`
`110`	`109`	`}`
`111`	`110`
`112`	`111`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ namespace Umbraco.Cms.Integrations.Search.Algolia.Api.Management.Controllers`
`20`	`20`	`[BackOfficeRoute($"{Constants.ManagementApi.RootPath}/v{{version:apiVersion}}/search")]`
`21`	`21`	`[Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)]`
`22`	`22`	`[MapToApi(Constants.ManagementApi.GroupName)]`
`23`		`- public abstract class SearchControllerBase`
	`23`	`+ public abstract class SearchControllerBase : Controller`
`24`	`24`	`{`
`25`	`25`	`protected IAlgoliaIndexService IndexService { get; }`
`26`	`26`