Fix API schema issues

Author: asvishnyakov

VirtoCommerce.Storefront/Infrastructure/Swagger/ApiSchemaOptions.cs

@@ -0,0 +1,13 @@
+using System;
+
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public class ApiSchemaOptions
+    {
+        public bool NameAndOrderRequestBody { get; set; }
+
+        public bool NotNullableReferenceTypesInArrays { get; set; }
+
+        public OpenApiSpecificationVersion OpenApiSpecificationVersion { get; set; }
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/ApiSchemaVersion.cs

@@ -0,0 +1,8 @@
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public enum ApiSchemaVersion
+    {
+        V1,
+        V2
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/NameAndOrderRequestBodyFilter.cs

@@ -0,0 +1,36 @@
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public class NameAndOrderRequestBodyFilter: IRequestBodyFilter
+    {
+        private readonly SwaggerOptions _swaggerOptions;
+
+        public NameAndOrderRequestBodyFilter(IOptions<SwaggerOptions> swaggerOptions)
+        {
+            _swaggerOptions = swaggerOptions.Value;
+        }
+
+        public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext context)
+        {
+            // Even if it's v2 or request body shouldn't be named
+            // we want name it because of bugs and different approaches in generation tools
+            var bodyName = _swaggerOptions.Schema.NameAndOrderRequestBody
+                ? context.BodyParameterDescription.Name
+                : "body";
+            requestBody.Extensions.Add("x-name", new OpenApiString(bodyName));
+            requestBody.Extensions.Add("x-codegen-request-body-name", new OpenApiString(bodyName));
+            requestBody.Extensions.Add("x-ms-requestBody-name", new OpenApiString(bodyName));
+
+            if (_swaggerOptions.Schema.NameAndOrderRequestBody)
+            {
+                var bodyPosition = context.BodyParameterDescription.ParameterInfo().Position;
+                requestBody.Extensions.Add("x-position", new OpenApiInteger(bodyPosition));
+                requestBody.Extensions.Add("x-ms-requestBody-index", new OpenApiInteger(bodyPosition));
+            }
+        }
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/NewtonsoftJsonIgnoreFilter.cs

@@ -0,0 +1,8 @@
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public enum OpenApiSpecificationVersion
+    {
+        V2,
+        V3
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/OpenApiSpecificationVersion.cs

@@ -0,0 +1,42 @@
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public class ParameterOrderFilter: IParameterFilter
+    {
+        private SwaggerOptions _swaggerOptions;
+
+        public ParameterOrderFilter(IOptions<SwaggerOptions> swaggerOptions)
+        {
+            _swaggerOptions = swaggerOptions.Value;
+        }
+
+        public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
+        {
+            if (_swaggerOptions.Schema.NameAndOrderRequestBody)
+            {
+                // Explicitly specify parameters position
+                // Position for store and language is unknown and they should be last, so use int.MaxValue relative values
+                if (context.ParameterInfo != null)
+                {
+                    parameter.Extensions.Add("x-position", new OpenApiInteger(context.ParameterInfo.Position));
+                }
+                else
+                {
+                    switch (parameter.Name)
+                    {
+                        case "store":
+                            parameter.Extensions.Add("x-position", new OpenApiInteger(int.MaxValue - 1));
+                            break;
+                        case "language":
+                            parameter.Extensions.Add("x-position", new OpenApiInteger(int.MaxValue));
+                            break;
+                    }
+                }
+            }
+        }
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/OptionalParametersFilter.cs

@@ -0,0 +1,13 @@
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public class RequireRequestBodyFilter: IRequestBodyFilter
+    {
+        public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext context)
+        {
+            requestBody.Required = true;
+        }
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/ParameterOrderFilter.cs

@@ -0,0 +1,7 @@
+namespace VirtoCommerce.Storefront.Infrastructure.Swagger
+{
+    public class SwaggerOptions
+    {
+        public ApiSchemaOptions Schema { get; set; }
+    }
+}

VirtoCommerce.Storefront/Infrastructure/Swagger/RequireRequestBodyFilter.cs

@@ -346,28 +346,33 @@ public void ConfigureServices(IServiceCollection services)
                 options.MaxAge = TimeSpan.FromDays(30);
             });
 
+            services.Configure<SwaggerOptions>(Configuration.GetSection("Swagger").Bind);
+
             // Register the Swagger generator, defining 1 or more Swagger documents
             services.AddSwaggerGen(c =>
             {
                 c.SwaggerDoc("v1", new OpenApiInfo { Title = "Storefront REST API documentation", Version = "v1" });
                 c.IgnoreObsoleteProperties();
                 c.IgnoreObsoleteActions();
+                c.ParameterFilter<ParameterOrderFilter>();
+                c.RequestBodyFilter<NameAndOrderRequestBodyFilter>();
+                c.RequestBodyFilter<RequireRequestBodyFilter>();
                 // To include 401 response type to actions that requires Authorization
                 c.OperationFilter<AuthResponsesOperationFilter>();
                 c.OperationFilter<ConsumeFromBodyFilter>();
-                c.OperationFilter<FileResponseTypeFilter>();
-                c.OperationFilter<OptionalParametersFilter>();
                 c.OperationFilter<ArrayInQueryParametersFilter>();
+                c.OperationFilter<FileResponseTypeFilter>();
                 c.OperationFilter<FileUploadOperationFilter>();
                 c.SchemaFilter<EnumSchemaFilter>();
-                c.SchemaFilter<NewtonsoftJsonIgnoreFilter>();
+                c.SchemaGeneratorOptions.UseAllOfToExtendReferenceSchemas = true;
 
                 // Use method name as operation ID, i.e. ApiAccount.GetOrganization instead of /storefrontapi/account/organization (will be treated as just organization method)
                 c.CustomOperationIds(apiDesc => apiDesc.TryGetMethodInfo(out var methodInfo) ? methodInfo.Name : null);
 
                 // To avoid errors with repeating type names
                 c.CustomSchemaIds(type => (Attribute.GetCustomAttribute(type, typeof(SwaggerSchemaIdAttribute)) as SwaggerSchemaIdAttribute)?.Id ?? type.FriendlyId());
             });
+            services.AddSwaggerGenNewtonsoftSupport();
 
             services.AddResponseCompression();
 
@@ -421,7 +426,12 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
             });
 
             // Enable middleware to serve generated Swagger as a JSON endpoint.
-            app.UseSwagger(c => c.RouteTemplate = "docs/{documentName}/docs.json");
+            app.UseSwagger(c =>
+            {
+                var options = app.ApplicationServices.GetService<IOptions<SwaggerOptions>>().Value;
+                c.SerializeAsV2 = options.Schema.OpenApiSpecificationVersion == OpenApiSpecificationVersion.V2;
+                c.RouteTemplate = "docs/{documentName}/docs.json";
+            });
 
             var rewriteOptions = new RewriteOptions();
             // Load IIS url rewrite rules from external file