From c30c1c2f12d0fb9abbcd15436e09a07e47bb9eb4 Mon Sep 17 00:00:00 2001
From: Krzysztof Pajak <krzysiek@grandnode.com>
Date: Thu, 9 Jan 2025 19:58:12 +0100
Subject: [PATCH] Enhance OpenAPI docs (#556)

---
 .../Extensions/OpenApiOptionsExtensions.cs    | 20 +++++++++++++++----
 .../Infrastructure/OpenApiStartup.cs          |  2 ++
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/Modules/Grand.Module.Api/Extensions/OpenApiOptionsExtensions.cs b/src/Modules/Grand.Module.Api/Extensions/OpenApiOptionsExtensions.cs
index 6e1266257..100b9012a 100644
--- a/src/Modules/Grand.Module.Api/Extensions/OpenApiOptionsExtensions.cs
+++ b/src/Modules/Grand.Module.Api/Extensions/OpenApiOptionsExtensions.cs
@@ -1,6 +1,7 @@
 using Grand.Module.Api.Attributes;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 
 namespace Grand.Module.Api.Infrastructure.Extensions
@@ -45,7 +46,8 @@ public static void AddOperationTransformer(this OpenApiOptions options)
                         Name = "$orderby",
                         AllowReserved = true,
                         In = ParameterLocation.Query,
-                        Description = "Order items by property values",
+                        Description = "Order items by property values (LINQ notation)",
+                        Example = new OpenApiString("Name, DisplayOrder"),
                         Required = false,
                         Schema = new OpenApiSchema {
                             Type = "string"
@@ -55,7 +57,8 @@ public static void AddOperationTransformer(this OpenApiOptions options)
                         Name = "$filter",
                         AllowReserved = true,
                         In = ParameterLocation.Query,
-                        Description = "Filter items by property values",
+                        Description = "Filter items by property values (LINQ notation) ",
+                        Example = new OpenApiString("Name == \"John\""),
                         Required = false,
                         Schema = new OpenApiSchema {
                             Type = "string"
@@ -65,7 +68,8 @@ public static void AddOperationTransformer(this OpenApiOptions options)
                         Name = "$select",
                         AllowReserved = true,
                         In = ParameterLocation.Query,
-                        Description = "Select specific properties from the model",
+                        Description = "Select specific properties from the model (LINQ notation)",
+                        Example = new OpenApiString("Id, Name"),
                         Required = false,
                         Schema = new OpenApiSchema {
                             Type = "string"
@@ -98,7 +102,7 @@ public static void AddCsrfTokenTransformer(this OpenApiOptions options)
         public static void AddContactDocumentTransformer(this OpenApiOptions options, string name, string version)
         {
             options.AddDocumentTransformer((document, context, cancellationToken) =>
-            {
+            {                
                 document.Info = new OpenApiInfo {
                     Description = "Grandnode API",
                     Title = name,
@@ -117,5 +121,13 @@ public static void AddContactDocumentTransformer(this OpenApiOptions options, st
                 return Task.CompletedTask;
             });
         }
+        public static void AddClearServerDocumentTransformer(this OpenApiOptions options)
+        {
+            options.AddDocumentTransformer((document, context, cancellationToken) =>
+            {
+                document.Servers.Clear();
+                return Task.CompletedTask;
+            });
+        }
     }
 }
diff --git a/src/Modules/Grand.Module.Api/Infrastructure/OpenApiStartup.cs b/src/Modules/Grand.Module.Api/Infrastructure/OpenApiStartup.cs
index e0637ad46..f235ed519 100644
--- a/src/Modules/Grand.Module.Api/Infrastructure/OpenApiStartup.cs
+++ b/src/Modules/Grand.Module.Api/Infrastructure/OpenApiStartup.cs
@@ -74,6 +74,7 @@ private void ConfigureBackendApi(IServiceCollection services)
             options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
             options.AddSchemaTransformer<EnumSchemaTransformer>();
             options.AddOperationTransformer();
+            options.AddClearServerDocumentTransformer();
         });
     }
 
@@ -87,6 +88,7 @@ private void ConfigureFrontendApi(IServiceCollection services)
             options.AddSchemaTransformer<EnumSchemaTransformer>();
             options.AddSchemaTransformer<IgnoreFieldSchemaTransformer>();
             options.AddCsrfTokenTransformer();
+            options.AddClearServerDocumentTransformer();
         });
 
         //api description provider