使用 Swashbuckle 在 Swagger 中显示枚举值和引用的 class

Question

我正在使用 Swashbuckle 生成 Swagger 输出。在我的模型上，我有以下属性:

public FieldValue? MyProperty { get; set; }

FieldValue 是一个简单的 class，可以包含一个 ID 和一个名称：

public class FieldValue
{
    /// <summary>
    /// The numerical represenation of the value.
    /// </summary>
    /// <example>1</example>
    public string Id { get; set; }

    /// <summary>
    /// The textual represenation of the value.
    /// </summary>
    /// <example>SomeValue</example>
    public string Name { get; set; }
}

通过我们代码中的一些业务逻辑，一组可能的键值对（ID 和名称）被映射到此属性。

现在，我想在我的 Swagger 输出中的 enum 标记中显示 MyProperty 的所有可能值。使用 ISchemaFilter 的实现，MyProperty 属性上的自定义属性并使用 allOf 而不是简单的 ref，我设法将值添加到我的 JSON 输出，见下文。使用 allOf 而不是 ref 的原因是 ref 将覆盖引用架构上的所有属性。因此，当我使用 allOf 时，它会在文档中保留我的 description 和 enum 字段。

{
    "components": {
        "schemas": {
            "FieldValue": {
                "type": "object",
                "properties": {
                    "Id": {
                        "type": "string",
                        "description": "The numerical represenation of the value.",
                        "nullable": true,
                    },
                    "Name": {
                        "type": "string",
                        "description": "The textual represenation of the value.",
                        "nullable": true,
                    }
                }
            },
            "MyProperty": {
                "enum": [
                    "1: EnumValue1",
                    "2: EnumValue2",
                    "3: EnumValue3"
                ],
                "allOf": [{
                        "$ref": "#/components/schemas/FieldValue"
                    }
                ],
                "description": "Some description",
                "nullable": true
            }
    }
}

不过，这不会显示 Swagger UI 中的枚举值。它确实显示了描述。

这个 Swagger 文档有效吗？如果不是，我怎样才能使它有效并显示 MyProperty?

的枚举

Answer 1

您的用例的正确表示是：

  "MyProperty": {
    "enum": [
      {"Id": "1", "Name": "EnumValue1"},
      {"Id": "2", "Name": "EnumValue2"},
      {"Id": "3", "Name": "EnumValue3"}
    ],
    "allOf": [
       { "$ref": "#/components/schemas/FieldValue" }
     ],
    "description": "Some description",
    "nullable": true
  }

但是，几乎没有工具支持包含对象文字的枚举。我建议在 MyProperty 属性.

的 description 中提及可能的 Id 和 Name 值

使用 Swashbuckle 在 Swagger 中显示枚举值和引用的 class

Displaying enum values together with a referenced class in Swagger using Swashbuckle

swagger

swagger-ui

swashbuckle

openapi