Enhance OpenAPI docs (#556)

grandnode · Jan 9, 2025 · c30c1c2 · c30c1c2
1 parent 0007a08
commit c30c1c2
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 4 deletions.
diff --git 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
@@ -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