使用 swagger，如何正确记录被序列化为字符串的 POCO 值属性？答案

【问题标题】：Using swagger, how can I correctly document a POCO-valued property that gets serialized as a string?使用 swagger，如何正确记录被序列化为字符串的 POCO 值属性？
【发布时间】：2018-01-01 16:43:49
【问题描述】：

我发现这个不错type-safe enum pattern，我觉得很酷。

该类确实只有公共静态属性和private constructor，并且可以从string 隐式推断。我将它用作我的模型的属性，当我传递string 时，它会在 asp.net 核心 Web api 控制器中正确获取model-binded。传递无效的string 值也可以正常工作，因为binder 能够设置ModelSate=false。我在这一行有一些东西：

class Mymodel
{
   public TypeSafeEnum TypeSafeEnum { get; set; }
   public string Name { get; set; }
   // the rest of props
}

在一些 swagger api 文档中，该属性被视为一个对象，因此试图帮助的 swagger 将给出示例输入模型：

{
  "typeSafeEnum": {},
  "name": "string",
  // the rest
}

大摇大摆的只是看到一个没有公共属性的对象。

有没有一种形式可以大摇大摆地告诉我我实际上期待的是string？还是我会欺骗我的客户，因为并非所有字符串值都有效？但是我又该如何提供有意义的提示呢？

【问题讨论】：

你是如何生成你的招摇文档的？如果您使用的是Swashbuckle.AspNetCore，那么此链接似乎是相关的：Override Schema for Specific Types。

标签： c# json.net swagger

【解决方案1】：

如果属性是字符串，Swagger 会将其记录为字符串。字符串显然可以接受任何东西。如果您只想将某些值传递给字符串，并且希望在 Swagger 文档中清楚地记录它，请使用枚举。您还可以使用正则表达式之类的属性验证器（或编写您自己的自定义验证器），但它们不会记录在案，它们仅在验证失败时显示。 IE。对于正则表达式，如果它未能通过正则表达式，它将返回一个 Json，说明此字段未通过此正则表达式，但正则表达式不会出现在 swagger 文档中。

【讨论】：