时间戳

首页 > 解决方案 > 如何通过代码指定 Swagger 规范扩展？

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

问题描述

我正在尝试将自定义属性添加到生成的 swagger.json 的信息部分中。我发现很多文章都在讨论如何在 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"
});

这没有用。如何将自定义属性（规范扩展）添加到 api 信息？

标签： c#asp.net-coreswaggeropenapiasp.net-core-5.0

解决方案

我发现您可以轻松地将自定义属性（规范扩展）添加到OpenApiInfo的 Extension 属性。您不需要创建自己的类来实现IOpenApiExtensionDictionary 的值。我使用的 Swagger nuget 包附带的类是OpenApiString

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。还有很多其他的。

推荐阅读