Add annotation to hide underlying resource ID type in OpenAPI document

Author: bkoelman

src/JsonApiDotNetCore.OpenApi.Swashbuckle/Annotations/HideResourceIdTypeInOpenApiAttribute.cs

@@ -0,0 +1,15 @@
+namespace JsonApiDotNetCore.OpenApi.Swashbuckle.Annotations;
+
+/// <summary>
+/// Hides the underlying resource ID type in OpenAPI documents.
+/// </summary>
+/// <remarks>
+/// For example, when used on a resource type that implements <c><![CDATA[IIdentifiable<long>]]></c>, excludes the <c>format</c> property on the ID
+/// schema. As a result, the ID type is displayed as <c>string</c> instead of
+/// <c>
+/// string($int64)
+/// </c>
+/// in SwaggerUI.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Struct)]
+public sealed class HideResourceIdTypeInOpenApiAttribute : Attribute;

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

@@ -1,4 +1,7 @@
+using System.Reflection;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Middleware;
+using JsonApiDotNetCore.OpenApi.Swashbuckle.Annotations;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
@@ -7,32 +10,48 @@ namespace JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Components;
 internal sealed class ResourceIdSchemaGenerator
 {
     private readonly SchemaGenerator _defaultSchemaGenerator;
+    private readonly IControllerResourceMapping _controllerResourceMapping;
 
-    public ResourceIdSchemaGenerator(SchemaGenerator defaultSchemaGenerator)
+    public ResourceIdSchemaGenerator(SchemaGenerator defaultSchemaGenerator, IControllerResourceMapping controllerResourceMapping)
     {
         ArgumentNullException.ThrowIfNull(defaultSchemaGenerator);
+        ArgumentNullException.ThrowIfNull(controllerResourceMapping);
 
         _defaultSchemaGenerator = defaultSchemaGenerator;
+        _controllerResourceMapping = controllerResourceMapping;
     }
 
-    public OpenApiSchema GenerateSchema(ResourceType resourceType, SchemaRepository schemaRepository)
+    public OpenApiSchema GenerateSchema(ParameterInfo parameter, SchemaRepository schemaRepository)
     {
-        ArgumentNullException.ThrowIfNull(resourceType);
+        ArgumentNullException.ThrowIfNull(parameter);
+        ArgumentNullException.ThrowIfNull(schemaRepository);
+
+        Type? controllerType = parameter.Member.ReflectedType;
+        ConsistencyGuard.ThrowIf(controllerType == null);
+
+        ResourceType? resourceType = _controllerResourceMapping.GetResourceTypeForController(controllerType);
+        ConsistencyGuard.ThrowIf(resourceType == null);
 
-        return GenerateSchema(resourceType.IdentityClrType, schemaRepository);
+        return GenerateSchema(resourceType, schemaRepository);
     }
 
-    public OpenApiSchema GenerateSchema(Type resourceIdClrType, SchemaRepository schemaRepository)
+    public OpenApiSchema GenerateSchema(ResourceType resourceType, SchemaRepository schemaRepository)
     {
-        ArgumentNullException.ThrowIfNull(resourceIdClrType);
+        ArgumentNullException.ThrowIfNull(resourceType);
         ArgumentNullException.ThrowIfNull(schemaRepository);
 
-        OpenApiSchema idSchema = _defaultSchemaGenerator.GenerateSchema(resourceIdClrType, schemaRepository);
+        OpenApiSchema idSchema = _defaultSchemaGenerator.GenerateSchema(resourceType.IdentityClrType, schemaRepository);
         ConsistencyGuard.ThrowIf(idSchema.Reference != null);
 
         idSchema.Type = "string";
 
-        if (resourceIdClrType != typeof(string))
+        var hideIdTypeAttribute = resourceType.ClrType.GetCustomAttribute<HideResourceIdTypeInOpenApiAttribute>();
+
+        if (hideIdTypeAttribute != null)
+        {
+            idSchema.Format = null;
+        }
+        else if (resourceType.IdentityClrType != typeof(string))
         {
             // When using string IDs, it's discouraged (but possible) to use an empty string as primary key value, because
             // some things won't work: get-by-id, update and delete resource are impossible, and rendered links are unusable.

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/JsonApiSchemaGenerator.cs

@@ -34,7 +34,7 @@ public OpenApiSchema GenerateSchema(Type schemaType, SchemaRepository schemaRepo
 
         if (parameterInfo is { Name: "id" } && IsJsonApiParameter(parameterInfo))
         {
-            return _resourceIdSchemaGenerator.GenerateSchema(schemaType, schemaRepository);
+            return _resourceIdSchemaGenerator.GenerateSchema(parameterInfo, schemaRepository);
         }
 
         DocumentSchemaGenerator? schemaGenerator = GetDocumentSchemaGenerator(schemaType);