Add support for OpenAPI.NET 2.0

Author: bkoelman

package-versions.props

@@ -33,9 +33,12 @@
   <PropertyGroup Condition="'$(TargetFramework)' == 'net10.0'">
     <!-- Published dependencies (only update on major version change) -->
     <EntityFrameworkCoreFrozenVersion>10.0.*-*</EntityFrameworkCoreFrozenVersion>
+    <SwashbuckleFrozenVersion>9.0.0-pr.3283.*</SwashbuckleFrozenVersion>
 
     <!-- Non-published dependencies (these are safe to update, won't cause a breaking change) -->
     <AspNetCoreVersion>10.0.*-*</AspNetCoreVersion>
+    <SwashbuckleVersion>9.0.0-pr.3283.*</SwashbuckleVersion>
+    <MicrosoftApiServerVersion>10.0.*-*</MicrosoftApiServerVersion>
     <EntityFrameworkCoreVersion>10.0.*-*</EntityFrameworkCoreVersion>
     <EntityFrameworkCorePomeloVersion>9.0.*-*</EntityFrameworkCorePomeloVersion>
   </PropertyGroup>

src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
   <PropertyGroup>
-    <TargetFrameworks>net10.0;net9.0;net8.0</TargetFrameworks>
+    <TargetFrameworks>net10.0</TargetFrameworks>
     <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
     <OpenApiDocumentsDirectory>GeneratedSwagger</OpenApiDocumentsDirectory>
   </PropertyGroup>

src/Examples/JsonApiDotNetCoreExample/SetOpenApiServerAtBuildTimeFilter.cs

@@ -16,6 +16,8 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
     {
         if (_httpContextAccessor.HttpContext == null)
         {
+            swaggerDoc.Servers ??= new List<OpenApiServer>();
+
             swaggerDoc.Servers.Add(new OpenApiServer
             {
                 Url = "https://localhost:44340"

src/JsonApiDotNetCore.OpenApi.Swashbuckle/ConfigureSwaggerGenOptions.cs

@@ -74,6 +74,7 @@ public void Configure(SwaggerGenOptions options)
         options.DocumentFilter<StringEnumOrderingFilter>();
         options.DocumentFilter<SetSchemaTypeToObjectDocumentFilter>();
         options.DocumentFilter<UnusedComponentSchemaCleaner>();
+        options.DocumentFilter<SortSchemasFilter>();
     }
 
     private List<Type> SelectDerivedTypes(Type baseType)

src/JsonApiDotNetCore.OpenApi.Swashbuckle/JsonApiDotNetCore.OpenApi.Swashbuckle.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>net10.0;net8.0</TargetFrameworks>
+    <TargetFrameworks>net10.0</TargetFrameworks>
     <IsPackable>true</IsPackable>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <OpenApiGenerateDocuments>false</OpenApiGenerateDocuments>

src/JsonApiDotNetCore.OpenApi.Swashbuckle/MicrosoftOpenApiCompatibilityExtensions.cs

@@ -0,0 +1,24 @@
+using Microsoft.OpenApi.Models;
+
+namespace JsonApiDotNetCore.OpenApi.Swashbuckle;
+
+internal static class MicrosoftOpenApiCompatibilityExtensions
+{
+    public static void SetNullable(this OpenApiSchema schema, bool nullable)
+    {
+        ArgumentNullException.ThrowIfNull(schema);
+
+        if (nullable)
+        {
+            schema.Type ??= JsonSchemaType.Null;
+            schema.Type |= JsonSchemaType.Null;
+        }
+        else
+        {
+            if (schema.Type != null)
+            {
+                schema.Type &= ~JsonSchemaType.Null;
+            }
+        }
+    }
+}

src/JsonApiDotNetCore.OpenApi.Swashbuckle/OpenApiSchemaExtensions.cs

@@ -1,4 +1,5 @@
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.Interfaces;
 
 namespace JsonApiDotNetCore.OpenApi.Swashbuckle;
 
@@ -9,7 +10,7 @@ public static void ReorderProperties(this OpenApiSchema fullSchema, IEnumerable<
         ArgumentNullException.ThrowIfNull(fullSchema);
         ArgumentNullException.ThrowIfNull(propertyNamesInOrder);
 
-        var propertiesInOrder = new Dictionary<string, OpenApiSchema>();
+        var propertiesInOrder = new Dictionary<string, IOpenApiSchema>();
 
         foreach (var propertyName in propertyNamesInOrder)
         {
@@ -24,7 +25,7 @@ public static void ReorderProperties(this OpenApiSchema fullSchema, IEnumerable<
         fullSchema.Properties = propertiesInOrder;
     }
 
-    public static OpenApiSchema WrapInExtendedSchema(this OpenApiSchema source)
+    public static OpenApiSchema WrapInExtendedSchema(this IOpenApiSchema source)
     {
         ArgumentNullException.ThrowIfNull(source);
 
@@ -34,11 +35,11 @@ public static OpenApiSchema WrapInExtendedSchema(this OpenApiSchema source)
         };
     }
 
-    public static OpenApiSchema UnwrapLastExtendedSchema(this OpenApiSchema source)
+    public static IOpenApiSchema UnwrapLastExtendedSchema(this IOpenApiSchema source)
     {
         ArgumentNullException.ThrowIfNull(source);
 
-        if (source.AllOf is { Count: > 0 })
+        if (source is OpenApiSchema && source.AllOf is { Count: > 0 })
         {
             return source.AllOf.Last();
         }

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/AtomicOperationCodeSchemaGenerator.cs

@@ -1,6 +1,7 @@
 using JsonApiDotNetCore.Serialization.Objects;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.References;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Components;
@@ -19,22 +20,15 @@ public AtomicOperationCodeSchemaGenerator(SchemaGenerationTracer schemaGeneratio
         _schemaIdSelector = schemaIdSelector;
     }
 
-    public OpenApiSchema GenerateSchema(AtomicOperationCode operationCode, SchemaRepository schemaRepository)
+    public OpenApiSchemaReference GenerateSchema(AtomicOperationCode operationCode, SchemaRepository schemaRepository)
     {
         ArgumentNullException.ThrowIfNull(schemaRepository);
 
         var schemaId = _schemaIdSelector.GetAtomicOperationCodeSchemaId(operationCode);
 
         if (schemaRepository.Schemas.ContainsKey(schemaId))
         {
-            return new OpenApiSchema
-            {
-                Reference = new OpenApiReference
-                {
-                    Id = schemaId,
-                    Type = ReferenceType.Schema
-                }
-            };
+            return new OpenApiSchemaReference(schemaId);
         }
 
         using var traceScope = _schemaGenerationTracer.TraceStart(this, operationCode);
@@ -43,8 +37,8 @@ public OpenApiSchema GenerateSchema(AtomicOperationCode operationCode, SchemaRep
 
         var fullSchema = new OpenApiSchema
         {
-            Type = "string",
-            Enum = [new OpenApiString(enumValue)]
+            Type = JsonSchemaType.String,
+            Enum = [enumValue]
         };
 
         var referenceSchema = schemaRepository.AddDefinition(schemaId, fullSchema);

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/DataContainerSchemaGenerator.cs

@@ -3,6 +3,7 @@
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SwaggerComponents;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.References;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Components;
@@ -27,14 +28,14 @@ public DataContainerSchemaGenerator(SchemaGenerationTracer schemaGenerationTrace
         _resourceGraph = resourceGraph;
     }
 
-    public OpenApiSchema GenerateSchemaForCommonResourceDataInResponse(SchemaRepository schemaRepository)
+    public OpenApiSchemaReference GenerateSchemaForCommonResourceDataInResponse(SchemaRepository schemaRepository)
     {
         ArgumentNullException.ThrowIfNull(schemaRepository);
 
         return _dataSchemaGenerator.GenerateSchemaForCommonData(typeof(ResourceInResponse), schemaRepository);
     }
 
-    public OpenApiSchema GenerateSchema(Type dataContainerSchemaType, ResourceType resourceType, bool forRequestSchema, bool canIncludeRelated,
+    public OpenApiSchemaReference GenerateSchema(Type dataContainerSchemaType, ResourceType resourceType, bool forRequestSchema, bool canIncludeRelated,
         SchemaRepository schemaRepository)
     {
         ArgumentNullException.ThrowIfNull(dataContainerSchemaType);

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/DataSchemaGenerator.cs

@@ -1,12 +1,16 @@
 using System.Collections.Concurrent;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Nodes;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiMetadata;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SwaggerComponents;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.Interfaces;
+using Microsoft.OpenApi.Models.References;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Components;
@@ -79,7 +83,7 @@ public DataSchemaGenerator(SchemaGenerationTracer schemaGenerationTracer, Schema
         _resourceDocumentationReader = resourceDocumentationReader;
     }
 
-    public OpenApiSchema GenerateSchema(Type dataSchemaType, bool forRequestSchema, SchemaRepository schemaRepository)
+    public OpenApiSchemaReference GenerateSchema(Type dataSchemaType, bool forRequestSchema, SchemaRepository schemaRepository)
     {
         // For a given resource (identifier) type, we always generate the full type hierarchy. Discriminator mappings
         // are managed manually, because there's no way to intercept in the Swashbuckle recursive component schema generation.
@@ -114,11 +118,11 @@ public OpenApiSchema GenerateSchema(Type dataSchemaType, bool forRequestSchema,
 
         using var traceScope = _schemaGenerationTracer.TraceStart(this, dataSchemaType);
 
-        referenceSchemaForData = _defaultSchemaGenerator.GenerateSchema(dataSchemaType, schemaRepository);
-        var fullSchemaForData = schemaRepository.Schemas[referenceSchemaForData.Reference.Id];
+        referenceSchemaForData = (OpenApiSchemaReference)_defaultSchemaGenerator.GenerateSchema(dataSchemaType, schemaRepository);
+        var fullSchemaForData = (OpenApiSchema)schemaRepository.Schemas[referenceSchemaForData.Reference.Id];
         fullSchemaForData.AdditionalPropertiesAllowed = false;
 
-        var inlineSchemaForData = fullSchemaForData.UnwrapLastExtendedSchema();
+        var inlineSchemaForData = (OpenApiSchema)fullSchemaForData.UnwrapLastExtendedSchema();
 
         SetAbstract(inlineSchemaForData, resourceSchemaType);
         SetResourceType(inlineSchemaForData, resourceType, schemaRepository);
@@ -142,7 +146,7 @@ public OpenApiSchema GenerateSchema(Type dataSchemaType, bool forRequestSchema,
 
         if (RequiresRootObjectTypeInDataSchema(resourceSchemaType, forRequestSchema))
         {
-            fullSchemaForData.Extensions[SetSchemaTypeToObjectDocumentFilter.RequiresRootObjectTypeKey] = new OpenApiBoolean(true);
+            fullSchemaForData.Extensions[SetSchemaTypeToObjectDocumentFilter.RequiresRootObjectTypeKey] = new OpenApiAny(true);
         }
 
         traceScope.TraceSucceeded(referenceSchemaForData.Reference.Id);
@@ -202,7 +206,7 @@ public OpenApiSchema GenerateSchema(Type dataSchemaType, bool forRequestSchema,
         return boxedSchemaType.Value;
     }
 
-    public OpenApiSchema GenerateSchemaForCommonData(Type commonDataSchemaType, SchemaRepository schemaRepository)
+    public OpenApiSchemaReference GenerateSchemaForCommonData(Type commonDataSchemaType, SchemaRepository schemaRepository)
     {
         ArgumentNullException.ThrowIfNull(commonDataSchemaType);
         ArgumentNullException.ThrowIfNull(schemaRepository);
@@ -219,9 +223,9 @@ public OpenApiSchema GenerateSchemaForCommonData(Type commonDataSchemaType, Sche
 
         var fullSchema = new OpenApiSchema
         {
-            Type = "object",
+            Type = JsonSchemaType.Object,
             Required = new SortedSet<string>([JsonApiPropertyName.Type]),
-            Properties = new Dictionary<string, OpenApiSchema>
+            Properties = new Dictionary<string, IOpenApiSchema>
             {
                 [JsonApiPropertyName.Type] = referenceSchemaForResourceType.WrapInExtendedSchema(),
                 [referenceSchemaForMeta.Reference.Id] = referenceSchemaForMeta.WrapInExtendedSchema()
@@ -234,7 +238,7 @@ public OpenApiSchema GenerateSchemaForCommonData(Type commonDataSchemaType, Sche
             },
             Extensions =
             {
-                ["x-abstract"] = new OpenApiBoolean(true)
+                ["x-abstract"] = new OpenApiAny(true)
             }
         };
 
@@ -272,7 +276,7 @@ private static void SetAbstract(OpenApiSchema fullSchema, ResourceSchemaType res
     {
         if (resourceSchemaType.ResourceType.ClrType.IsAbstract && resourceSchemaType.SchemaOpenType != typeof(IdentifierInRequest<>))
         {
-            fullSchema.Extensions["x-abstract"] = new OpenApiBoolean(true);
+            fullSchema.Extensions["x-abstract"] = new OpenApiAny(true);
         }
     }
 
@@ -367,8 +371,8 @@ private void SetFieldSchemaMembers(OpenApiSchema fullSchemaForData, ResourceSche
     {
         var propertyNameInSchema = forAttributes ? JsonApiPropertyName.Attributes : JsonApiPropertyName.Relationships;
 
-        var referenceSchemaForFields = fullSchemaForData.Properties[propertyNameInSchema].UnwrapLastExtendedSchema();
-        var fullSchemaForFields = schemaRepository.Schemas[referenceSchemaForFields.Reference.Id];
+        var referenceSchemaForFields = (OpenApiSchemaReference)fullSchemaForData.Properties[propertyNameInSchema].UnwrapLastExtendedSchema();
+        var fullSchemaForFields = (OpenApiSchema)schemaRepository.Schemas[referenceSchemaForFields.Reference.Id];
         fullSchemaForFields.AdditionalPropertiesAllowed = false;
 
         SetAbstract(fullSchemaForFields, resourceSchemaTypeForData);
@@ -437,7 +441,7 @@ private ResourceSchemaType GetResourceSchemaTypeForFieldsProperty(ResourceSchema
         return ResourceSchemaType.Create(fieldsConstructedType, _resourceGraph);
     }
 
-    private OpenApiSchema GenerateSchemaForCommonFields(Type commonFieldsSchemaType, SchemaRepository schemaRepository)
+    private OpenApiSchemaReference GenerateSchemaForCommonFields(Type commonFieldsSchemaType, SchemaRepository schemaRepository)
     {
         if (schemaRepository.TryLookupByType(commonFieldsSchemaType, out var referenceSchema))
         {
@@ -450,9 +454,9 @@ private OpenApiSchema GenerateSchemaForCommonFields(Type commonFieldsSchemaType,
 
         var fullSchema = new OpenApiSchema
         {
-            Type = "object",
+            Type = JsonSchemaType.Object,
             Required = new SortedSet<string>([OpenApiMediaTypeExtension.FullyQualifiedOpenApiDiscriminatorPropertyName]),
-            Properties = new Dictionary<string, OpenApiSchema>
+            Properties = new Dictionary<string, IOpenApiSchema>
             {
                 [OpenApiMediaTypeExtension.FullyQualifiedOpenApiDiscriminatorPropertyName] = referenceSchemaForResourceType.WrapInExtendedSchema()
             },
@@ -464,7 +468,7 @@ private OpenApiSchema GenerateSchemaForCommonFields(Type commonFieldsSchemaType,
             },
             Extensions =
             {
-                ["x-abstract"] = new OpenApiBoolean(true)
+                ["x-abstract"] = new OpenApiAny(true)
             }
         };
 
@@ -489,7 +493,7 @@ private void MapInDiscriminator(ResourceSchemaType resourceSchemaType, bool forR
                 : resourceSchemaType.ChangeResourceType(baseResourceType).SchemaConstructedType;
 
             var referenceSchemaForBase = schemaRepository.LookupByType(baseSchemaType);
-            var inlineSchemaForBase = schemaRepository.Schemas[referenceSchemaForBase.Reference.Id].UnwrapLastExtendedSchema();
+            var inlineSchemaForBase = (OpenApiSchema)schemaRepository.Schemas[referenceSchemaForBase.Reference.Id].UnwrapLastExtendedSchema();
 
             inlineSchemaForBase.Discriminator ??= new OpenApiDiscriminator
             {
@@ -545,9 +549,9 @@ private void MapResourceTypeInEnum(string publicName, SchemaRepository schemaRep
         var schemaId = _schemaIdSelector.GetResourceTypeSchemaId(null);
         var fullSchema = schemaRepository.Schemas[schemaId];
 
-        if (!fullSchema.Enum.Any(openApiAny => openApiAny is OpenApiString openApiString && openApiString.Value == publicName))
+        if (!fullSchema.Enum.Any(openApiAny => openApiAny is JsonValue openApiString && openApiString.GetValueKind() == JsonValueKind.String && openApiString.GetValue<string>() == publicName))
         {
-            fullSchema.Enum.Add(new OpenApiString(publicName));
+            fullSchema.Enum.Add(publicName);
         }
     }
 
@@ -572,11 +576,11 @@ private void GenerateDataSchemasForDirectlyDerivedTypes(ResourceSchemaType resou
 
             using var traceScope = _schemaGenerationTracer.TraceStart(this, resourceSchemaTypeForDerived.SchemaConstructedType);
 
-            var referenceSchemaForDerived = _defaultSchemaGenerator.GenerateSchema(derivedSchemaType, schemaRepository);
-            var fullSchemaForDerived = schemaRepository.Schemas[referenceSchemaForDerived.Reference.Id];
+            var referenceSchemaForDerived = (OpenApiSchemaReference)_defaultSchemaGenerator.GenerateSchema(derivedSchemaType, schemaRepository);
+            var fullSchemaForDerived = (OpenApiSchema)schemaRepository.Schemas[referenceSchemaForDerived.Reference.Id];
             fullSchemaForDerived.AdditionalPropertiesAllowed = false;
 
-            var inlineSchemaForDerived = fullSchemaForDerived.UnwrapLastExtendedSchema();
+            var inlineSchemaForDerived = (OpenApiSchema)fullSchemaForDerived.UnwrapLastExtendedSchema();
             SetResourceFields(inlineSchemaForDerived, resourceSchemaTypeForDerived, forRequestSchema, schemaRepository);
 
             SetAbstract(inlineSchemaForDerived, resourceSchemaTypeForDerived);
@@ -605,7 +609,7 @@ private void GenerateDataSchemasForDirectlyDerivedTypes(ResourceSchemaType resou
             if (RequiresRootObjectTypeInDataSchema(resourceSchemaTypeForDerived, forRequestSchema))
             {
                 var fullSchemaForData = schemaRepository.Schemas[referenceSchemaForDerived.Reference.Id];
-                fullSchemaForData.Extensions[SetSchemaTypeToObjectDocumentFilter.RequiresRootObjectTypeKey] = new OpenApiBoolean(true);
+                fullSchemaForData.Extensions[SetSchemaTypeToObjectDocumentFilter.RequiresRootObjectTypeKey] = new OpenApiAny(true);
             }
 
             GenerateDataSchemasForDirectlyDerivedTypes(resourceSchemaTypeForDerived, forRequestSchema, schemaRepository);