Json schema $ref name for generic type changed with Swagger and OpenApi

Question

I am upgrading my .NET Core project from 2.2 to 3.1...

With that I also updated Swagger version, which is now based on OpenApi. The .json schema for my API I got from Swagger, has changed the $ref name for my custom generic types. I use these types in a lot of responses.

I am not sure if it is because of the OpenApi specification, or I haven't configured something right.

This is an example of my controller method:

/// <summary>
/// Gets recording sets by search settings.
/// </summary>
/// <response code="200">The recording sets were returned correctly.</response>
/// <response code="401">The unauthorized access.</response>
/// <response code="406">The not acceptable format.</response>
/// <response code="415">The unsupported media type.</response>
/// <response code="500">The unexpected error.</response>
/// <param name="recordingSetSearchSettings">The search settings of the recording set.</param>
/// <returns>The found recording sets.</returns>
[HttpGet]
[ProducesResponseType(typeof(IDataPage<RecordingSet>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(void), StatusCodes.Status401Unauthorized)]
[ProducesResponseType(typeof(void), StatusCodes.Status406NotAcceptable)]
[ProducesResponseType(typeof(void), StatusCodes.Status415UnsupportedMediaType)]
[ProducesResponseType(typeof(ApiErrorSummary), StatusCodes.Status500InternalServerError)]
[SwaggerOperation(OperationId = "SearchRecordingSets")]
public IDataPage<RecordingSet> Get([FromQuery(Name = "")] RecordingSetSearchSettings recordingSetSearchSettings)
{
    return recordingSetService.Search(recordingSetSearchSettings);
}

Notice the IDataPage<RecordingSet> in ProducesResponseType

This is how my $ref name in .json used to look like: IDataPage[RecordingSet] (I want to maintain this, because I use custom NSwag .exe to generate Client methods for FrontEnd)

This is how the $ref name in .json looks now: RecordingSetIDataPage

Is this a configuration problem, or the specification changed, so I have to implement some custom approach in order to support this?

Jakub Jakub · Accepted Answer · 2020-11-03T09:38:26

I've found corresponding answer on Swashbuckle github - https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1803

The convention has changed and you can use the old way, with defining TypeExtension - FriendlyId and using it in CustomSchemaIds

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v4.0.1/src/Swashbuckle.AspNetCore.SwaggerGen/Generator/TypeExtensions.cs#L10

services.AddSwaggerGen(c =>
    {
        // ... your definitions ...
        c.CustomSchemaIds(i => i.FriendlyId());
    });

Json schema $ref name for generic type changed with Swagger and OpenApi

1 Answers