为什么 autorest 用 Swagger 中的对象替换我的自定义结构？

Question

我创建了一个自定义的readonlystruct 来定义我称之为TenantId 的不可变值类型：

[DebuggerDisplay("ID={m_internalId.ToString()}")]
[JsonConverter(typeof(TenantIdJsonConverter))]
public readonly struct TenantId : IEquatable<TenantId>
{
    private readonly Guid m_internalId;

    public static TenantId New => new(Guid.NewGuid());

    private TenantId(Guid id)
    {
        m_internalId = id;
    }

    public TenantId(TenantId otherTenantId)
    {
       m_internalId = otherTenantId.m_internalId;
    }

    ...
}

我还定义了一个名为 PurchaseContract 的合同，它是 HTTP 响应的一部分：

[JsonObject(MemberSerialization.OptIn)]
public sealed class PurchaseContract
{
    [JsonProperty(PropertyName = "tenantId")]
    public TenantId TenantId { get; }
        
    [JsonProperty(PropertyName = "total")]
    public double Total { get; }
}

最后，我设置了一个 HTTP 触发函数，它将返回一个 PurchaseContract 的实例。目前，已经在ProducesResponseTypeAttribute进行了描述：

[ApiExplorerSettings(GroupName = "Purchases")]
[ProducesResponseType(typeof(PurchaseContract), (int) HttpStatusCode.OK)]
[FunctionName("v1-get-purchase")]
public Task<IActionResult> RunAsync
(
    [HttpTrigger(AuthorizationLevel.Anonymous, "GET", Route = "v1/purchases")]
    HttpRequest httpRequest,
    [SwaggerIgnore] 
            ClaimsPrincipal claimsPrincipal
)
{
    //  Stuff to do.
    return Task.FromResult((IActionResult)new OkResult());
}

在我的Startup 课程中，我正在设置这样的招摇：

private static void ConfigureSwashBuckle(IFunctionsHostBuilder functionsHostBuilder)
{
    functionsHostBuilder.AddSwashBuckle(Assembly.GetExecutingAssembly(), options =>
            {
                options.SpecVersion = OpenApiSpecVersion.OpenApi3_0;
                options.AddCodeParameter = true;
                options.PrependOperationWithRoutePrefix = true;
                options.XmlPath = "FunctionApp.xml";
                options.Documents = new []
                {
                    new SwaggerDocument
                    {
                        Title = "My API,
                        Version = "v1",
                        Name = "v1",
                        Description = "Description of my API",
                    }
                };
            });
        }

在swagger UI页面中，我可以看到它看起来不错：

问题

使用 Autorest 创建 C# 客户端时出现意外结果。不知何故，TenantId 结构被删除并替换为object：

为什么会这样？我应该怎么做才能自动生成 TenantId，就像客户端中的 PurchaseContract 一样？

详情

这是版本信息。

• 在netcore3.1上运行的Function App V3；
• OpenApi 3.0；
• Autorest Core 3.0.6274、autorest.csharp' (~2.3.79->2.3.91) 和 autorest.modeler' (2.3.55->2.3.55)；
• NuGet 包AzureExtensions.Swashbuckle;

Answer 1

我开始研究Swashbuckle.AspNetCore.SwaggerGen 的源代码，以了解我的readonly struct 是如何被解释的。这一切都发生在JsonSerializerDataContractResolver 类中，在方法@​​987654328@ 中，该方法为提供的类型确定DataContract：

public DataContract GetDataContractForType(Type type)
{
    if (type.IsOneOf(typeof(object), typeof(JsonDocument), typeof(JsonElement)))
    {
        ...
    }

    if (PrimitiveTypesAndFormats.ContainsKey(type))
    {
        ...
    }

    if (type.IsEnum)
    {
        ...
    }

    if (IsSupportedDictionary(type, out Type keyType, out Type valueType))
    {
        ...
    }

    if (IsSupportedCollection(type, out Type itemType))
    {
        ...
    }

    return DataContract.ForObject(
        underlyingType: type,
        properties: GetDataPropertiesFor(type, out Type extensionDataType),
        extensionDataType: extensionDataType,
        jsonConverter: JsonConverterFunc);
}

我的自定义 struct TenantId 不符合这些条件中的任何一个，因此，它回退到被视为 object（最后一条语句）。

然后我继续查看现有的tests，以了解该类的使用情况，看看我是否可以更改任何内容。令人惊讶的是，我发现了一个名为 GenerateSchema_SupportsOption_CustomTypeMappings 的测试（第 356 行），它显示了一种提供自定义映射的方法（参见该方法的第一条语句）：

[Theory]
[InlineData(typeof(ComplexType), typeof(ComplexType), "string")]
[InlineData(typeof(GenericType<int, string>), typeof(GenericType<int, string>), "string")]
[InlineData(typeof(GenericType<,>), typeof(GenericType<int, int>), "string")]
public void GenerateSchema_SupportsOption_CustomTypeMappings(
            Type mappingType,
            Type type,
            string expectedSchemaType)
{
    var subject = Subject(configureGenerator: c => c.CustomTypeMappings.Add(mappingType, () => new OpenApiSchema { Type = "string" }));

    var schema = subject.GenerateSchema(type, new SchemaRepository());

    Assert.Equal(expectedSchemaType, schema.Type);
    Assert.Empty(schema.Properties);
}

就我而言，我想让我的TenantId 映射到string。为此，我在 Function App 启动时编辑了 SwashBuckle 的配置：

private static void ConfigureSwashBuckle(IFunctionsHostBuilder functionsHostBuilder)
{
    functionsHostBuilder.AddSwashBuckle(Assembly.GetExecutingAssembly(), options =>
    {
        ...
        options.ConfigureSwaggerGen = (swaggerGenOptions) => swaggerGenOptions.MapType<TenantId>(() => new OpenApiSchema {Type = "string"});
    });
}

就是这样，TenantId 现在在 Swagger 中被视为 string。