Document OpenAPI limitations (#1715)

Author: bkoelman

Diff for: docs/usage/openapi-client.md

@@ -1,3 +1,6 @@
+> [!WARNING]
+> OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.
+
 # OpenAPI clients
 
 After [enabling OpenAPI](~/usage/openapi.md), you can generate a typed JSON:API client for your API in various programming languages.
@@ -317,3 +320,37 @@ demonstrates how to use them. It uses local IDs to:
 - Assign the todo-item to the created person
 
 ---
+
+## Known limitations
+
+# [NSwag](#tab/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 | https://github.com/RicoSuter/NSwag/issues/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](#tab/kiota)
+
+| Limitation | Workaround | Links |
+| --- | --- | --- |
+| Properties are always nullable | - | https://github.com/microsoft/kiota/issues/3911 |
+| JSON:API query strings are inaccessible | Use `SetQueryStringHttpMessageHandler.CreateScope` from `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/3800 |
+| Properties set to `null` are sent twice | - | https://github.com/microsoft/kiota-dotnet/issues/535 |
+| HTTP 304 (Not Modified) is not properly recognized | Catch `ApiException` and inspect the response status code | https://github.com/microsoft/kiota/issues/4190, https://github.com/microsoft/kiota-dotnet/issues/531 |
+| Generator warns about unsupported formats | Use `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/4227 |
+| `Stream` response for HEAD request | - | https://github.com/microsoft/kiota/issues/4245 |
+| Unhelpful exception messages | - | https://github.com/microsoft/kiota/issues/4349 |
+| Discriminator properties aren't being set automatically | - |  https://github.com/microsoft/kiota/issues/4618 |
+| Discriminator mappings must be repeated in every derived type used in responses | `JsonApiDotNetCore.OpenApi.Swashbuckle` package contains workaround | https://github.com/microsoft/kiota/issues/2432 |
+| `x-abstract` in `openapi.json` is ignored | - | |
+| No MSBuild / IDE support | Use `KiotaReference` from `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/3005 |
+| Incorrect nullability in API methods | Use `KiotaReference` from `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/3944 |
+| Generated code for JSON:API extensions does not compile | `JsonApiDotNetCore.OpenApi.Swashbuckle` package contains workaround | |
+| Properties are always sent in alphabetic order | - | https://github.com/microsoft/kiota/issues/4680 |
+
+---

Diff for: docs/usage/openapi-documentation.md

@@ -1,3 +1,6 @@
+> [!WARNING]
+> OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.
+
 # OpenAPI documentation
 
 After [enabling OpenAPI](~/usage/openapi.md), you can expose a documentation website with SwaggerUI, Redoc and/or Scalar.

Diff for: docs/usage/openapi.md

@@ -1,3 +1,6 @@
+> [!WARNING]
+> OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.
+
 # OpenAPI
 
 Exposing an [OpenAPI document](https://swagger.io/specification/) for your JSON:API endpoints enables to provide a
@@ -7,9 +10,6 @@ Exposing an [OpenAPI document](https://swagger.io/specification/) for your JSON:
 The [JsonApiDotNetCore.OpenApi.Swashbuckle](https://github.com/json-api-dotnet/JsonApiDotNetCore/pkgs/nuget/JsonApiDotNetCore.OpenApi.Swashbuckle) NuGet package
 provides OpenAPI support for JSON:API by integrating with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
 
-> [!WARNING]
-> OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.
-
 ## Getting started
 
 1.  Install the `JsonApiDotNetCore.OpenApi.Swashbuckle` NuGet package: