如何通过代码指定Swagger规范扩展？

Question

我正在尝试将自定义属性添加到生成的swagger.json的info部分。我发现很多文章都在讨论如何在json中添加属性，方法是在它们前面加上"x-“。(例如：https://swagger.io/specification/#specification-extensions)

但是，我找不到任何说明如何通过C#代码做到这一点的东西。(当前使用的是.NET 5)

我们目前将标准属性设置如下：

options.SwaggerDoc(Swagger.Version, new OpenApiInfo
{
  Title = "Service Api",
  Version = Swagger.Version,
  Description = "This describes the routes associated with the Service Api."
});

为了测试这一点，我尝试像这样扩展OpenApiInfo：

public class CustomInfo : OpenApiInfo
{
  [JsonPropertyName("x-test")]
  public String Test;
}

然后像这样修改SwaggerDoc：

options.SwaggerDoc(Swagger.Version, new CustomInfo
{
  Title = "Service Api",
  Version = Swagger.Version,
  Description = "This describes the routes associated with the Service Api.",
  Test = "New Value"
});

这不起作用。如何在接口信息中添加自定义属性(规范扩展)？

Answer 1

我发现您可以轻松地将自定义属性(规范扩展)添加到OpenApiInfo的扩展属性中。您不需要为字典的值创建自己的实现IOpenApiExtension的类。

options.SwaggerDoc(Swagger.Version, new OpenApiInfo
{
  Title = "Service Api",
  Version = Swagger.Version,
  Description = "This describes the routes associated with the Service Api.",
  Extensions = new Dictionary<string, IOpenApiExtension>
  {
    { "x-company", new OpenApiString("Company Name") },
    { "x-contact", new OpenApiString("contact@email.com") }
  }
});

还有许多其他现成的类，如OpenApiBoolean、OpenApiDateTime，或者如果您需要一个对象，则可以使用OpenApiObject。还有很多其他的。