使用Swashback在Swagger中显示枚举值和引用的类

Question

我正在使用Swashback生成Swagger输出。在我的模型I上，具有以下属性：

public FieldValue? MyProperty { get; set; }

FieldValue是一个简单的类，可以保存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标签中显示所有可能的值。使用ISchemaFilter的一个实现，即MyProperty属性上的一个自定义属性，并使用allOf而不是简单的ref，我成功地在我的JSON输出中添加了值，见下文。使用allOf而不仅仅是ref的原因是ref将覆盖引用架构上的所有属性。因此，当我使用allOf时，它将我的描述和枚举字段保留在文档中。

{
    "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属性的描述中提及可能的Id和Name值。