OpenAPI: Generalization of naming conventions

JsonApiDotNetCore.sln.DotSettings

@@ -15,6 +15,8 @@ JsonApiDotNetCore.ArgumentGuard.NotNull($EXPR$, $NAME$);</s:String>
 	<s:Int64 x:Key="/Default/CodeEditing/NullCheckPatterns/PatternTypeNamesToPriority/=JetBrains_002EReSharper_002EFeature_002EServices_002ECSharp_002ENullChecking_002ETraceAssertPattern/@EntryIndexedValue">50</s:Int64>
 	<s:Boolean x:Key="/Default/CodeInspection/CodeAnnotations/PropagateAnnotations/@EntryValue">False</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeInspection/ExcludedFiles/FileMasksToSkip/=swagger_002Ejson/@EntryIndexedValue">True</s:Boolean>
+	<s:String x:Key="/Default/CodeInspection/GeneratedCode/GeneratedFileMasks/=swagger_002Eg_002Ejson/@EntryIndexedValue">swagger.g.json</s:String>
+	<s:String x:Key="/Default/CodeInspection/GeneratedCode/GeneratedFileMasks/=swagger_002Ejson/@EntryIndexedValue">swagger.json</s:String>
 	<s:String x:Key="/Default/CodeInspection/Highlighting/AnalysisEnabled/@EntryValue">SOLUTION</s:String>
 	<s:Boolean x:Key="/Default/CodeInspection/Highlighting/IdentifierHighlightingEnabled/@EntryValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeInspection/Highlighting/IncludeWarningsInSwea/@EntryValue">True</s:Boolean>

src/JsonApiDotNetCore.OpenApi.Client/ApiException.cs

@@ -0,0 +1,25 @@
+using JetBrains.Annotations;
+
+// We cannot rely on generating ApiException as soon as we are generating multiple clients, see https://github.com/RicoSuter/NSwag/issues/2839#issuecomment-776647377.
+// Instead, we configure NSwag to point to the exception below in the generated code.
+
+// ReSharper disable once CheckNamespace
+namespace JsonApiDotNetCore.OpenApi.Client.Exceptions;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+public sealed class ApiException : Exception
+{
+    public int StatusCode { get; }
+
+    public string? Response { get; }
+
+    public IReadOnlyDictionary<string, IEnumerable<string>> Headers { get; }
+
+    public ApiException(string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, Exception innerException)
+        : base($"{message}\n\nStatus: {statusCode}\nResponse: \n{response ?? "(null)"}", innerException)
+    {
+        StatusCode = statusCode;
+        Response = response;
+        Headers = headers;
+    }
+}

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/NullableResourceIdentifierResponseDocument.cs

@@ -1,19 +1,25 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.Resources;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 
+// Types in the current namespace are never touched by ASP.NET ModelState validation, therefore using a non-nullable reference type for a property does not
+// imply this property is required. Instead, we use [Required] explicitly, because this is how Swashbuckle is instructed to mark properties as required.
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 internal sealed class NullableResourceIdentifierResponseDocument<TResource> : NullableSingleData<ResourceIdentifierObject<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceIdentifierDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/NullableSecondaryResourceResponseDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -10,10 +11,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 internal sealed class NullableSecondaryResourceResponseDocument<TResource> : NullableSingleData<ResourceObjectInResponse<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/PrimaryResourceResponseDocument.cs

@@ -1,21 +1,23 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.Resources;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 
-// Types in the current namespace are never touched by ASP.NET ModelState validation, therefore using a non-nullable reference type for a property does not
-// imply this property is required. Instead, we use [Required] explicitly, because this is how Swashbuckle is instructed to mark properties as required.
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 internal sealed class PrimaryResourceResponseDocument<TResource> : SingleData<ResourceObjectInResponse<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/ResourceCollectionResponseDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -10,10 +11,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 internal sealed class ResourceCollectionResponseDocument<TResource> : ManyData<ResourceObjectInResponse<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceCollectionDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/ResourceIdentifierCollectionResponseDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -10,10 +11,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 internal sealed class ResourceIdentifierCollectionResponseDocument<TResource> : ManyData<ResourceIdentifierObject<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceIdentifierCollectionDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/ResourceIdentifierResponseDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -10,10 +11,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 internal sealed class ResourceIdentifierResponseDocument<TResource> : SingleData<ResourceIdentifierObject<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceIdentifierDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Documents/SecondaryResourceResponseDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -10,10 +11,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 internal sealed class SecondaryResourceResponseDocument<TResource> : SingleData<ResourceObjectInResponse<TResource>>
     where TResource : IIdentifiable
 {
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 
+    [JsonPropertyName("jsonapi")]
     public JsonapiObject Jsonapi { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("links")]
     public LinksInResourceDocument Links { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/JsonapiObject.cs

@@ -1,15 +1,20 @@
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 internal sealed class JsonapiObject
 {
+    [JsonPropertyName("version")]
     public string Version { get; set; } = null!;
 
+    [JsonPropertyName("ext")]
     public ICollection<string> Ext { get; set; } = null!;
 
+    [JsonPropertyName("profile")]
     public ICollection<string> Profile { get; set; } = null!;
 
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInRelationshipObject.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,8 +8,10 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInRelationshipObject
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("related")]
     public string Related { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInResourceCollectionDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,16 +8,22 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInResourceCollectionDocument
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 
+    [JsonPropertyName("describedby")]
     public string Describedby { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("first")]
     public string First { get; set; } = null!;
 
+    [JsonPropertyName("last")]
     public string Last { get; set; } = null!;
 
+    [JsonPropertyName("prev")]
     public string Prev { get; set; } = null!;
 
+    [JsonPropertyName("next")]
     public string Next { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInResourceDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,7 +8,9 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInResourceDocument
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 
+    [JsonPropertyName("describedby")]
     public string Describedby { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInResourceIdentifierCollectionDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,19 +8,26 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInResourceIdentifierCollectionDocument
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 
+    [JsonPropertyName("describedby")]
     public string Describedby { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("related")]
     public string Related { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("first")]
     public string First { get; set; } = null!;
 
+    [JsonPropertyName("last")]
     public string Last { get; set; } = null!;
 
+    [JsonPropertyName("prev")]
     public string Prev { get; set; } = null!;
 
+    [JsonPropertyName("next")]
     public string Next { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInResourceIdentifierDocument.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,10 +8,13 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInResourceIdentifierDocument
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 
+    [JsonPropertyName("describedby")]
     public string Describedby { get; set; } = null!;
 
     [Required]
+    [JsonPropertyName("related")]
     public string Related { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Links/LinksInResourceObject.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
@@ -7,5 +8,6 @@ namespace JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 internal sealed class LinksInResourceObject
 {
     [Required]
+    [JsonPropertyName("self")]
     public string Self { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/ManyData.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 
@@ -9,5 +10,6 @@ internal abstract class ManyData<TData>
     where TData : ResourceIdentifierObject
 {
     [Required]
+    [JsonPropertyName("data")]
     public ICollection<TData> Data { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/NullableSingleData.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 
@@ -9,5 +10,6 @@ internal abstract class NullableSingleData<TData>
     where TData : ResourceIdentifierObject
 {
     [Required]
+    [JsonPropertyName("data")]
     public TData? Data { get; set; }
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Relationships/NullableToOneRelationshipInResponse.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -11,7 +12,9 @@ internal sealed class NullableToOneRelationshipInResponse<TResource> : NullableS
     where TResource : IIdentifiable
 {
     [Required]
+    [JsonPropertyName("links")]
     public LinksInRelationshipObject Links { get; set; } = null!;
 
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 }

src/JsonApiDotNetCore.OpenApi/JsonApiObjects/Relationships/ToManyRelationshipInResponse.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 using JetBrains.Annotations;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Links;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
@@ -11,7 +12,9 @@ internal sealed class ToManyRelationshipInResponse<TResource> : ManyData<Resourc
     where TResource : IIdentifiable
 {
     [Required]
+    [JsonPropertyName("links")]
     public LinksInRelationshipObject Links { get; set; } = null!;
 
+    [JsonPropertyName("meta")]
     public IDictionary<string, object> Meta { get; set; } = null!;
 }