Skip to content

Document OpenAPI limitations #1715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 20, 2025
Merged

Document OpenAPI limitations #1715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions docs/usage/openapi-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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 |

---
3 changes: 3 additions & 0 deletions docs/usage/openapi-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
6 changes: 3 additions & 3 deletions docs/usage/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand Down
Loading