Document OpenAPI limitations

[bkoelman]

NSwag

Limitation	Workaround	Links
Partial POST/PATCH sends incorrect request	Use TrackChangesFor from JsonApiDotNetCore.OpenApi.Client.NSwag package
Exception thrown on successful HTTP status	Use TranslateAsync from JsonApiDotNetCore.OpenApi.Client.NSwag package	RicoSuter/NSwag#2499
No Accept header sent when only error responses define Content-Type	JsonApiDotNetCore.OpenApi.Swashbuckle package contains workaround
Schema type not always inferred with allOf	JsonApiDotNetCore.OpenApi.Swashbuckle package contains workaround
Generated code for JSON:API extensions does not compile	JsonApiDotNetCore.OpenApi.Swashbuckle package contains workaround
A project can't contain both JSON:API clients and regular OpenAPI clients	Use separate projects

Kiota

Limitation	Workaround	Links
Properties are always nullable	-	microsoft/kiota#3911
JSON:API query strings are inaccessible	Use SetQueryStringHttpMessageHandler.CreateScope from JsonApiDotNetCore.OpenApi.Client.Kiota package	microsoft/kiota#3800
HTTP 304 (Not Modified) is not properly recognized	Perhaps fixed in v1.16.1, needs verification	microsoft/kiota#4190
Generator warns about unsupported formats	Use JsonApiDotNetCore.OpenApi.Client.Kiota package	microsoft/kiota#4227
Unstable content of kiota-lock.json file	Might be fixed, needs verification	microsoft/kiota#4228
Stream response for HEAD request	-	microsoft/kiota#4245
Unhelpful exception messages	-	microsoft/kiota#4349
Discriminator properties aren't being set automatically	-	microsoft/kiota#4618
Discriminator mappings must be repeated in every derived type used in responses	JsonApiDotNetCore.OpenApi.Swashbuckle package contains workaround	microsoft/kiota#2432
x-abstract in openapi.json is ignored	-	-
No MSBuild / IDE support	Use KiotaReference from JsonApiDotNetCore.OpenApi.Client.Kiota package	microsoft/kiota#3005
Incorrect nullability in API methods	Use KiotaReference from JsonApiDotNetCore.OpenApi.Client.Kiota package	microsoft/kiota#3944
Generated code for JSON:API extensions does not compile	JsonApiDotNetCore.OpenApi.Swashbuckle package contains workaround