Swagger 如何处理位枚举标志

Question

我有一个类似于以下的枚举：

[Flags]
public enum MeteoType : ushort
{
    Wind = 1 << 0,
    Pressure = 1 << 1,
    Temperature = 1 << 2,
    Waves = 1 << 4,
    Currents = 1 << 9,
    Swell = 1 << 13,
    WindWave = 1 << 14,
}

我有一个模型；

public class Params
{
    public List<MeteoType> Meteo { get; set; } = new List<MeteoType>()
    {
        MeteoType.Wind
    };
    ....
}

在我的控制器方法中，我通过查询来请求该模型，如下所示：

public async Task<IActionResult> Get(int z, int x, int y, [FromQuery] Params parameters)

这让我在Swagger中看到了这个视图：

我使用List，因为它是一个标识，并且我希望能够选择多个元素。问题就从这里开始。当我选择多个元素时，链接会创建如下：

https://localhost:44311?Meteo=1&Meteo=2&Meteo=4&...

而不是

https://localhost:44311?Meteo=7&...

我应该如何使链接通过枚举值的总和生成，而不是一个接一个地生成所有枚举值？

- OhWelp

Answer 1

OpenAPI规范不支持按位枚举参数。您的Meteo参数需要在OpenAPI定义中仅定义为type: integer，即您需要调整注释以使其产生type: integer而不是type: array参数。消费者将需要手动提供正确的总和值。

# OpenAPI definition generated from the code

openapi: 3.0.0
...

paths:
  /something:
    get:

      parameters:
        - in: query
          name: Meteo
          schema:
            type: integer
          example: 7
          description: >-
            One of the following values, or a sum of multiple values:

             * 1 - Wind
             * 2 - Pressure
             * ...

            For example, 7 means Wind (1) + Pressure (2) + Temperature (4).

另外，您可以尝试forkSwagger UI并更改代码，以将所选列表值作为单个汇总值而不是多值参数发送。

- Helen