如何在 swagger 中修改示例 json？答案

【问题标题】：How do I modify the example json in swagger?如何在 swagger 中修改示例 json？
【发布时间】：2021-12-15 12:12:39
【问题描述】：

我正在尝试修改显示的示例 json，以测试 POST 是否有效。我应该从哪里修改这个？也就是说，我必须修改按下“试用”时显示的 json。

更准确地说，测试帖子的json如下：

{
"Cliente": 0,
  "CantidadRegistros": 0,
  "TotalesPrimerVencimiento": 0,
  "TotalesSegundoVencimiento": 0,
  "Detalle": [
    {
      "Consorcio": 0,
      "UnidadFuncional": 0,
      "Periodo": "string",
      "Propietario": "string",
      "Ubicacion": "string",
      "Email": "string",
      "FechaPrimerVencimiento": "2021-12-15",
      "ImportePrimerVencimiento": 0,
      "FechaSegundoVencimiento": "2021-12-15",
      "ImporteSegundoVencimiento": 0,
      "CodigoDePagoElectronico": "string",
      "CodigoDeBarras": "string"
    }
  ]
}

我要修改的是显示日期的格式。目前是dd-mm-yyyy，我想修改为dd/mm/yyyy

尝试使用以下 DisplayFormat 代码对其进行修改，但对我不起作用：

[JsonPropertyName("FechaSegundoVencimiento")]
[FromQuery(Name = "FechaSegundoVencimiento")]
[ModelBinder(BinderType = typeof(DateTimeModelBinder))]
[DisplayFormat(DataFormatString = "{0:dd/MM/yyyy}", ApplyFormatInEditMode = true)]
[DataType(DataType.Date)]
public DateTime? DueDate2 { get; set; }

我希望你的帮助！谢谢！

【问题讨论】：

我已经编辑了您问题上的标签以提及Swagger UI，我猜这就是这张截图的内容。 API 使用 C# 和 ASP.net 的事实似乎并不相关，因此我删除了这些标签。但是，最好edit 提供更多关于您到底想要做什么以及到目前为止您已经尝试过的详细信息 - 请记住，您已经关注这个问题一段时间了，但是阅读您的问题的人有只有您提供给他们的信息。
@IMSoP 与 ASP.NET/C# 部分相关，它们的 Swagger/OpenAPI 文档由 ASP.NET 特定库 Swashbuckle 生成。大概吧。
@CodeCaster 然后他们需要这么说 - 这就是我在编辑后留下评论的原因，以便他们在必要时进行澄清。问题只是说“我在哪里编辑这个？”并提到了 JSON 和 Swagger。据我所知，他们通过使用 awk 脚本解析源代码来生成文档。因为他们似乎同意你提到的 Swashbuckle，所以我添加了那个标签。
该示例显示为 yyyy-mm-dd，因为这是 OpenAPI 中 DataType.Date 的 expected format。如果您想使用另一种日期格式，您需要更改注释，以便它们生成这些字段只是type: string。或者将您的 API 更改为使用 yyyy-mm-dd。
哦，好的。现在我明白了。并从哪里修改 API，以便它期望另一种格式 DataType.DateTime @Helen ？

标签： swagger swagger-ui swashbuckle swashbuckle.aspnetcore

【解决方案1】：

using XML comments, generating documentation files on build and having Swashbuckle read these comments：

型号：

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

// ...

启动：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", ...);

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "Your.App.xml");
     c.IncludeXmlComments(filePath);
}

如果我没记错的话，这会为每个模型属性生成一个示例。因此，如果您在不同 API 之间重用模型并想要不同的示例，则需要扩展到其他库。

我使用过mattfrear/Swashbuckle.AspNetCore.Filters，您可以在其中使用[SwaggerRequestExample(typeof(...)] 和[SwaggerResponseExample(typeof(...))] 来注释您的方法，其中... 可以提供将序列化为JSON 的示例对象，但请注意，在各种情况下，他们建议使用 Swashbuckle 的内置方式。

然而，你说：

目前是dd-mm-yyyy，我想修改为dd/mm/yyyy

不要。 JSON 没有预定义的日期格式，但大多数 API 默认接受 ISO-8601(ish) 格式。不要让这种文化变得特定。

【讨论】：

完美！非常感谢@CodeCaster！我将对此进行测试并评论它是如何进行的。
为什么不建议我更改日期格式？
因为这样做很愚蠢。 JSON 是一种机器可读的格式。如果您想为人类格式化日期，请在将该日期呈现给人类时这样做。
当然，我需要这种格式，以便人们可以大摇大摆地加载他们的 JSON。我修改了我的问题。