swagger - ASP.NET 样板文件 : Constraining user Input DTO property value to specific set of values

Question

我最近开始使用 ASP.NET Boilerplate 作为我正在从事的项目的起点 - Asp.NET Core Web Api + Angular，我很难找到一些关于我看来的东西的信息像一个常见的使用问题。我会尽力解释我的意思。

我想要做的是拥有一个 API 端点，该端点采用需要限制为一组特定值的参数 - 因此，我想为此目的使用枚举。

就参数验证而言，这一切都很好，但我对如何使用 swagger 和 Nswag 为 fontend 共享代理生成的服务很好地工作感到困惑。

枚举参数在文档参数示例中显示为整数，因此仅通过查看 swagger 文档并不清楚可用值的集合是什么，因为 int 值对查看文档的用户没有意义。

让我们使用这样的示例，其中一种应用服务方法中使用的用户输入:

服务方式:

public async Task DoSomething(SomethingInput input)
{
    //some code handling user input
}

输入DTO:

public class SomethingInput : EntityDto<string>
{
    [EnumDataType(typeof(SomethingEnum))]
    public SomethingEnum Something { get; set; }

    public int SomeOtherData { get; set; }
}

枚举:

public enum SomethingEnum
{
    Option1,
    Option2,
    Option3
}

在这种情况下，SomethingInput 中 SomethingEnum 的可用值将显示为 0、1、3，而不是“Option1”、“Option2”、“Option2”。

我尝试将 DescribeAllEnumsAsStrings 用于 swagger 生成选项，这有助于文档，但它在 Angular 项目功能中产生了一个问题 - 具体来说，由于 Nswag 工具使用 DescribeAllEnumsAsStrings 生成枚举的方式 - 它期望更改租户失败值是整数，而不是字符串。

export enum IsTenantAvailableOutputState {
    Available = <any>"Available", 
    InActive = <any>"InActive", 
    NotFound = <any>"NotFound", 
}

API 返回的响应值是数字，这段代码不知道如何正确解析该值，因为枚举不再有整数值:

export class AppTenantAvailabilityState {
    static Available: number = IsTenantAvailableOutputState._1;
    static InActive: number = IsTenantAvailableOutputState._2;
    static NotFound: number = IsTenantAvailableOutputState._3;
}

这里的问题是，在用作用户输入的路由或 DTO 对象中使用此类受限参数的最佳做法是什么，以便它们在 swagger 文档中正确显示，并且在以下情况下不会在角度项目中分解任何内容使用 Nswag 工具重新生成共享代理？

Answer 1

我认为您需要将 StringEnumConverter 添加到 SerializerSettings 而不是 DescribeAllEnumsAsStrings()。换句话说，在 Startup.cs 的 ConfigureServices() 中你应该有这样的东西:

services
    .AddMvc(options => options.Filters.Add(new CorsAuthorizationFilterFactory(_defaultCorsPolicyName)))
    .AddJsonOptions(options => options.SerializerSettings.Converters.Add(new StringEnumConverter()));