SwaggerUI shows the wrong type/discriminator for POST /people

[fdlane]

SUMMARY

When generating OpenAPI with JADNC, the Swagger UI request example for creating a Person shows the JSON:API type (and nested discriminators) as "bars" instead of "people". This happens in the POST /people request body example. See attached screenshot.

DETAILS

Example Repo: https://github.com/fdlane/ExampleJsonApi

1. Steps to reproduce
2. Clone the repo above and run the API.
3. Open Swagger UI.
4. Expand POST /people.
5. Inspect the generated example request body.

Expected
data.type (and any discriminator fields) should reflect the concrete resource being created, i.e. "people" for Person.

Actual
data.type appears as "bars" in the example, and the nested discriminator properties inside attributes and relationships also show "bars" (see attached image).

VERSIONS USED

• JsonApiDotNetCore version: 5.8.1 and 5.8.1-preview.4
• ASP.NET Core version: net9
• Entity Framework Core version:
• Database provider: sqllite

[bkoelman]

Hi @fdlane, thanks for reporting this.

I can see how this is confusing. The reason you're seeing this is because type is modelled as a multi-value enumeration. SwaggerUI simply picks the first entry when generating the example. Scalar and ReDoc do the same. Here's the related schema:

Then why is it an enumeration? The answer to that has to do with inheritance. Looking at the swagger.json file (search for "The attributes and relationships of the person to create.", then follow the references), we see that createPersonRequestDocument defines the data property, whose structure is defined in dataInCreatePersonRequest. Jumping there, we see that it derives from resourceInCreateRequest, which has a type property, whose type is resourceType, which lists all three resource types.

In condensed form, here's the OpenAPI definition:

{
  "createPersonRequestDocument": {
    "required": [
      "data"
    ],
    "type": "object",
    "properties": {
      "data": {
        "allOf": [
          {
            "$ref": "#/components/schemas/dataInCreatePersonRequest"
          }
        ]
      },
      "meta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/meta"
          }
        ]
      }
    },
    "additionalProperties": false
  },
  "dataInCreatePersonRequest": {
    "type": "object",
    "allOf": [
      {
        "$ref": "#/components/schemas/resourceInCreateRequest"
      },
      {
        "type": "object",
        "properties": {
          "attributes": {
            "allOf": [
              {
                "$ref": "#/components/schemas/attributesInCreatePersonRequest"
              }
            ]
          },
          "relationships": {
            "allOf": [
              {
                "$ref": "#/components/schemas/relationshipsInCreatePersonRequest"
              }
            ]
          }
        },
        "additionalProperties": false
      }
    ],
    "additionalProperties": false
  },
  "resourceInCreateRequest": {
    "required": [
      "type"
    ],
    "type": "object",
    "properties": {
      "type": {
        "allOf": [
          {
            "$ref": "#/components/schemas/resourceType"
          }
        ]
      },
      "meta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/meta"
          }
        ]
      }
    },
    "additionalProperties": false,
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "bars": "#/components/schemas/dataInCreateBarRequest",
        "foos": "#/components/schemas/dataInCreateFooRequest",
        "people": "#/components/schemas/dataInCreatePersonRequest"
      }
    },
    "x-abstract": true
  },
  "resourceType": {
    "enum": [
      "bars",
      "foos",
      "people"
    ],
    "type": "string"
  }
}

Before adding support for JSON:API resource inheritance, each post/patch resource request schema used a dedicated single-valued enumeration. Perhaps it would be better to revert to that design. Though when resource inheritance is used, we still need to generate a multi-valued enumeration (resulting in the same problem), but at least it becomes less noticeable, as most users don't use resource inheritance.

I didn't realize this side effect when implementing support for resource inheritance. When an API client is generated using NSwag, it understands the inheritance structure and automatically supplies the proper resource type. With Kiota, it always needs to be specified anyway, ie:

I don't remember exactly why I made that change, possibly to reduce the number of schemas. I'll look into it, but it may take some time. Adding support for resource inheritance was a significant challenge that took me several months to complete. There are so many corner cases to handle and test. Fortunately, the test coverage is now in the codebase, but I'll still need to review all the cases.

[fdlane]

Huge thank you @bkoelman for the detailed response.

While working through a possible workaround, I noticed a change in generation behavior after introducing a HopEntity, which seemed to impact the issue. I’m in the process of creating an example to demonstrate these findings but wanted to share this early in case it helps with your investigation.

Extending our resource entities from an empty HopEntity appears to affect the inheritance hierarchy:

using ExampleJsonApi.Common.Entities;

namespace ExampleJsonApi.Entities;

public abstract class HopEntity : BaseEntity { }

Hopefully this might help.

[fdlane]

After further experimenting, it seems that the only effect of introducing HopEntity without [Resource] or [Attr] is that the type and discriminator now resolve to the alphabetically first entity that’s a concrete resource, rather than defaulting to BaseEntity.

Thanks for looking into this.

[bkoelman]

Possibly related: #1775, but that hasn't been released yet.

[bkoelman]

I've patched up the code to make this work with SwaggerUI and Kiota, but it can't be implemented for NSwag due to this limitation.