泛型类型的 Json 模式 $ref 名称随 Swagger 和 OpenApi 更改答案

【问题标题】：Json schema $ref name for generic type changed with Swagger and OpenApi泛型类型的 Json 模式 $ref 名称随 Swagger 和 OpenApi 更改
【发布时间】：2021-02-15 04:13:19
【问题描述】：

我正在将我的 .NET Core 项目从 2.2 升级到 3.1...

我还更新了 Swagger 版本，它现在基于 OpenApi。我从 Swagger 获得的 API 的 .json 架构更改了我的自定义泛型类型的 $ref 名称。我在很多回复中都使用这些类型。

我不确定是因为 OpenApi 规范，还是我没有正确配置。

这是我的控制器方法的示例：

/// <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);
}

注意ProducesResponseType中的IDataPage<RecordingSet>

这就是我在 .json 中的 $ref 名称过去的样子：IDataPage[RecordingSet]（我想保持这个，因为我使用自定义 NSwag .exe 为前端生成客户端方法）

这是 .json 中 $ref 名称现在的样子：RecordingSetIDataPage

这是一个配置问题，还是规范改变了，所以我必须实现一些自定义方法来支持这个？

【问题讨论】：

标签： c# .net-core swagger openapi swashbuckle

【解决方案1】：

我在 Swashbuckle github 上找到了相应的答案 - https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1803

约定已经改变，您可以使用旧方法，定义 TypeExtension - FriendlyId 并在 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());
    });

【讨论】：