OpenAPI: Previously used application/vnd.api+json returns 415 - Unsupported Media Type

[JohnStrim]

SUMMARY

First of all Great work with Integrating Open.Api and forming Swagger UI. I have a question concerning the supported media type we used so far: application/vnd.api+json.

DETAILS

I noticed that when I add the Swashbuckle prerelease package and I include it in the UI I have a problem with all my existing integrations. The reason appears to be the Content-Type of the request.
In all my current integrations I used this request Header:
Content-Type: application/vnd.api+json
When I Swashbuckle in API I get Status Code: 415 - Unsupported Media Type
The only way it works is if I set:
Content-Type: application/vnd.api+json; ext=openapi
Am I missing any configuration in order not to break compatibility with previous integrations while using Swagger?

STEPS TO REPRODUCE

1. Updated to JsonApiDotNetCore and JsonApiDotNetCore.OpenApi.Swashbuckle.
2. Include it in the code as mentioned in the documentation (I will provide the full Extension Method I created)
3. Run Solution, open Swagger Doc, try request (Executes successfully)
4. Open Postman with the same request and authentication but use the following header: Content-Type: application/vnd.api+json
5. Error Response: 415 - Unsupported Media Type

internal static IServiceCollection AddSwaggerDocumentation(this IServiceCollection services, IConfiguration configuration)
{
    services.AddOpenApiForJsonApi(options =>
    {
        var currentNs = configuration.GetCurrentNamespace();
        currentNs = string.IsNullOrEmpty(currentNs) ? currentNs : $"/{currentNs}";
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "External Services", Version = "v1" });
        options.AddServer(new OpenApiServer { Url = $"{currentNs}/api/externalservices" });
        options.AddSwaggerAuth();
        options.TagActionsBy(apiDesc =>
        {

            var controllerType = apiDesc.ActionDescriptor.EndpointMetadata
             .OfType<DisplayNameAttribute>()
             .FirstOrDefault()?.DisplayName;

            return new List<string> { controllerType ?? apiDesc.ActionDescriptor.RouteValues["controller"] };
        });

        options.DocInclusionPredicate((name, api) => true);

        options.OperationFilter<DefaultApiVersionFilter>();
    });

    return services;
}

internal static SwaggerGenOptions AddSwaggerAuth(this SwaggerGenOptions options)
{
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "Use JWT provided by Identity Service."
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });

    return options;
}

VERSIONS USED

• JsonApiDotNetCore version: 5.7.1
• JsonApiDotNetCore.OpenApi.Swashbuckle version: 5.7.1-preview.2
• .NET version: 8.0

[bkoelman]

We had to change the OpenAPI document structure and introduce the extension at https://www.jsonapi.net/ext/openapi/ to support resource inheritance. Our OpenAPI package cannot function without that anymore. It is explained at #1704.

Are your existing integrations based on an earlier version of our package, or something else?

[JohnStrim]

@bkoelman thank you for your response.

We were not using JsonApiDotNetCore.Open.Swashbuckle at all before.
What we want is that our client applications which are configured to call our API that follows JsonApi specification and still use as content type for their body: Content-Type: application/vnd.api+json

I understand why we need it for OpenApi integration and swagger ui but do we need to put it everywhere? It seems that the moment we stop calling method: AddSwaggerDocumentation that is mentioned above this extension in no longer recognized by the code.

[bkoelman]

Unfortunately, this is how our solution works. I wish things were simpler. The goal is to enable usage of all JsonApiDotNetCore features, which requires a JSON:API extension due to limitations in the OpenAPI spec itself.

In theory, we could make this conditional. But we don't want the document structure to radically change, after an API developer decides to use one of our features they didn't use before. That silently breaks existing clients. And for us it means an explosion of the set of possible combinations to test for, which is unfeasible.

Even if your API project doesn't use resource inheritance, we rely on OpenAPI inheritance to express returned includes, which is a mixture of types.

I understand this is inconvenient because you have a custom implementation that works differently. We aim to provide a stable solution for the document structure in future releases.

[JohnStrim]

I totally agree and understand.
What I would suggest to consider is that since openapi is used as an extension I would also hope that unless it's necessary to be used like for example when I'm on a Swagger UI then to continue to work as it used to just not to support all the fixes and correction you've made for OpenApi. Again this is merely a suggestion which is completely with no Knowledge of the issues and Challenges you've faced so far with the OpenApi Integration.

[bkoelman]

So if I understand your use case right, that would be: only offer a documentation website and not care about client generators. This makes it annoying that there's a different content type now. Users may be hand-crafting JSON requests and never use client generators, so why do we need the change?

I wonder if we could offer both content types. It depends on how client generators react to that, ie: will they always pick the first, or always the last, or does that vary per generator? It's a risky change, though; we can check what NSwag and Kiota do today, but that may change, and new generators may be added that break it.