Add extension to describe generics

[RicoSuter]

In JSON Schema/Swagger/OpenAPI you cannot define generics or templates, see: OAI/OpenAPI-Specification#957

This is a proposal how to implement generics with custom extensions.

Define a schema with generic parameters:

{
    "type": "object",
    "title": "KeyValuePair",  
    "properties": {
        "key": {
            "x-generic": "TKey"
        }, 
        "value": {
            "x-generic": "TValue"
        }
    }
}

Usage of the generic schema in a property:

{
    "properties": {
        "myPairProperty": {
            "x-generics": {
                "TKey": {
                    "type": "string"
                },
                "TValue": {
                    "type": "number"
                }
            }, 
            "oneOf": [
                {
                     "$ref": "#/definitions/KeyValuePair"
                }
            ]
        }
    }
}

• x-generic defined on JsonProperty: Defines a generic property (if one property has x-generic set, then the property and schema is generic). If the processor understands x-generic, it will ignore all other properties and instead replace the schema with the specified one. Otherwise you can define a default schema for processors which do not support this.
• x-generics defined on JsonSchema4: Defines the type of the generic parameters (i.e. an instance of the generic schema). If the property schema is generic, then all generic parameters from the generic schema must be defined in x-generics.
  • Update ActualPropertySchema (just for generator): Create copy of generic schema, replace the type parameters, and return it...
• Update JsonSchemaValidator

It’s important to note that this will only work with the complete NJsonSchema/NSwag toolchain and will probably break or yield wrong results when used with other tools. Ideally we’d also generate a reasonable fallback with eg any typing etc...

[grovesNL]

How should multiple generic parameters be handled with that schema definition?

[RicoSuter]

You would have multiple entries in the "x-generics" object.

[RicoSuter]

I've updated the sample

[mirata]

@RicoSuter I think this would be a really good thing to add actually. Happy to help out if I can commit some time.
I had a very complicated object I needed to deal with on the typescript side with multiple generics, and it really doesn't work well. I don't think it matters that this concept would only work within the NSwag toolchain - people would definitely make use of it.

[john-larson]

Is there any progress on this issue?

[marinasundstrom]

Is there any progress on this issue?

I am wondering the same.

[RicoSuter]

Is there any progress on this issue?

The answer is no there is no progress :-)... not planned as it is very custom to the NJsonSchema/NSwag toolchain - main recommendation is to avoid generics because other tools will not understand it.

[binginsin]

Was looking into generics and JSON schema recently and found this:
https://gist.github.com/kevinswiber/4ee078f7bee175852587aca738377168#file-page-schema-json-L32

Apparently generics can be supported using $dynamicRef, $dynamicAnchor and multiple schemas.

I'm not entirely sure how difficult this would be to implement, but I believe it may be possible to add generic support without going against the specification of OpenAPI, even if other generators don't have this implemented.

Interested to hear others' thoughts.

[antonGritsenko]

because other tools will not understand it.

IMHO this is bad argument, since each and very OpenAPI tool works in a very different way, and none of them fully support all aspects of the OpenAPI on different platform. NJsonSchema and NSwag are from .net world, so they should support generics, because its native of the platform.

[JohnGalt1717]

How is this still an issue in 2023 9 years after the first request for generics in the OpenAPI spec that basically all languages support or could just use object?

You should be able to define Page as a schema type, and to be valid, everywhere it's referenced should have to provide the ref/concrete type to TResult.

And that should be it. NSwag shouldn't have to be doing this, this should just be part of the OpenApi spec. But like Enums that it still has a mess of, this still isn't supported.

This is literally why people create new competing standards: Basics broken.

[mcDevnagh]

If generating Generic DTOs is too complicated, the could be an option to just use the generic types if generateDtoTypes is false. It would then fall upon the developer to "generate" the DTOs

Thus, it would generate

public virtual async System.Threading.Tasks.Task<ListResponse<Order>> GetOrdersAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken))

public virtual async System.Threading.Tasks.Task<ListResponseOfOrder> GetOrdersAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken))

Maybe an option to just using the schema IDs directly, since our schema ID for ListResponseOfOrder is ListResponse<Order>