Document public OpenAPI members, remove unused IJsonApiClient

Author: bkoelman

src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiException.cs

@@ -5,6 +5,9 @@
 
 namespace JsonApiDotNetCore.OpenApi.Client.NSwag;
 
+/// <summary>
+/// Replacement for the auto-generated <c>ApiException</c> class from NSwag.
+/// </summary>
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 public class ApiException(string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, Exception? innerException)
     : Exception($"HTTP {statusCode}: {message}", innerException)
@@ -14,6 +17,9 @@ public class ApiException(string message, int statusCode, string? response, IRea
     public IReadOnlyDictionary<string, IEnumerable<string>> Headers { get; } = headers;
 }
 
+/// <summary>
+/// Replacement for the auto-generated <c>ApiException&lt;TResult&gt;</c> class from NSwag.
+/// </summary>
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 public sealed class ApiException<TResult>(
     string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, TResult result, Exception? innerException)

src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiResponse.cs

@@ -3,6 +3,9 @@
 
 namespace JsonApiDotNetCore.OpenApi.Client.NSwag;
 
+/// <summary>
+/// Replacement for the auto-generated <c>SwaggerResponse</c> class from NSwag.
+/// </summary>
 [PublicAPI]
 public class ApiResponse(int statusCode, IReadOnlyDictionary<string, IEnumerable<string>> headers)
 {
@@ -71,6 +74,9 @@ public static async Task<ApiResponse> TranslateAsync(Func<Task<ApiResponse>> ope
     }
 }
 
+/// <summary>
+/// Replacement for the auto-generated <c>SwaggerResponse&lt;TResult&gt;</c> class from NSwag.
+/// </summary>
 [PublicAPI]
 public class ApiResponse<TResult>(int statusCode, IReadOnlyDictionary<string, IEnumerable<string>> headers, TResult result)
     : ApiResponse(statusCode, headers)

src/JsonApiDotNetCore.OpenApi.Client.NSwag/BlockedJsonInheritanceConverter.cs

@@ -4,6 +4,9 @@
 namespace JsonApiDotNetCore.OpenApi.Client.NSwag;
 
 // Referenced from liquid template, to ensure the built-in JsonInheritanceConverter from NSwag is never used.
+/// <summary>
+/// Exists to block usage of the default <c>JsonInheritanceConverter</c> from NSwag, which is incompatible with JSON:API.
+/// </summary>
 [PublicAPI]
 public abstract class BlockedJsonInheritanceConverter : JsonConverter
 {
@@ -31,11 +34,17 @@ public override bool CanConvert(Type objectType)
         return true;
     }
 
+    /// <summary>
+    /// Always throws an <see cref="InvalidOperationException"/>.
+    /// </summary>
     public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer)
     {
         throw new InvalidOperationException("JsonInheritanceConverter is incompatible with JSON:API and must not be used.");
     }
 
+    /// <summary>
+    /// Always throws an <see cref="InvalidOperationException"/>.
+    /// </summary>
     public override object ReadJson(JsonReader reader, Type objectType, object? existingValue, JsonSerializer serializer)
     {
         throw new InvalidOperationException("JsonInheritanceConverter is incompatible with JSON:API and must not be used.");

src/JsonApiDotNetCore.OpenApi.Client.NSwag/IJsonApiClient.cs

@@ -11,7 +11,8 @@
 namespace JsonApiDotNetCore.OpenApi.Client.NSwag;
 
 /// <summary>
-/// Implementation of <see cref="INotifyPropertyChanged" /> that doesn't detect changes.
+/// Implementation of <see cref="INotifyPropertyChanged" /> that unconditionally raises the <see cref="PropertyChanged" /> event when a property is
+/// assigned. Exists to support JSON:API partial POST/PATCH.
 /// </summary>
 [PublicAPI]
 public abstract class NotifyPropertySet : INotifyPropertyChanged