参数的 Swagger 默认值

Posted 2023-04-12

【中文标题】参数的 Swagger 默认值

【英文标题】：Swagger default value for parameter

【发布时间】：2018-06-20 23:04:12

【问题描述】：

如何为以下 API 生成的 swagger 中的属性定义默认值？

public class SearchQuery

        public string OrderBy  get; set; 

        [DefaultValue(OrderDirection.Descending)]
        public OrderDirection OrderDirection  get; set;  = OrderDirection.Descending;



public IActionResult SearchPendingCases(SearchQuery queryInput);

Swashbuckle 生成 OrderDirection 作为所需参数。我希望它是可选的并向客户端指示默认值（不确定 swagger 是否支持此）。

我不喜欢让属性类型可以为空。还有其他选择吗？理想情况下使用内置类...

我使用 Swashbuckle.AspNetCore - https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio

【问题讨论】：

你在使用 ServiceStack 吗？

@Sidron：不。我使用普通的 asp.net 内核和 swashbuckle

为什么要让 orderDirection 可以同时为空和可以为空...？

标题和答案都在谈论参数，但在问题的正文中，您询问了类中属性的默认值。

@MichaelFreidgeim：无论是作为类中的属性，还是方法中的参数，它们仍然只是swagger中操作的参数

【参考方案1】：

我总是像这样在参数本身上设置默认值：

public class TestPostController : ApiController

    public decimal Get(decimal x = 989898989898989898, decimal y = 1)
    
        return x * y;
    

这是 swagger-ui 上的样子：http://swashbuckletest.azurewebsites.net/swagger/ui/index#/TestPost/TestPost_Get

更新

在讨论 cmets 之后，我更新了 Swagger-Net 以通过反射阅读 DefaultValueAttribute 这是我正在使用的示例类：

public class MyTest

    [MaxLength(250)]
    [DefaultValue("HelloWorld")]
    public string Name  get; set; 
    public bool IsPassing  get; set; 

这是招摇 json 的样子：

"MyTest": 
  "type": "object",
  "properties": 
    "Name": 
      "default": "HelloWorld",
      "maxLength": 250,
      "type": "string"
    ,
    "IsPassing": 
      "type": "boolean"
    
  ,
  "xml": 
    "name": "MyTest"
  
,

Swagger-Net的源码在这里：https://github.com/heldersepu/Swagger-Net

而测试项目的源代码在这里：https://github.com/heldersepu/SwashbuckleTest

【讨论】：

我知道，但我有上课的理由。如果这可行，那么类定义的参数也应该可以正常工作

@Liero 我能给你的最好解释是，对于默认值，你需要一些我们可以在编译时得到的东西，但是直到有人实例化 SearchQuery 类后你的分配才会发生

当然，这就是注释属性（可以通过反射检索）存在的原因。也许 swashbuckle 确实支持开箱即用的 DefaultValueAttribute（或类似的解决方案），但我确信可以通过配置添加功能

但是@Liero 不要害怕！我有自己的 Swashbuckle 叉子，让我们看看我需要多长时间才能做到这一点......

很遗憾，它不是 asp.net 核心

【参考方案2】：

如果您可以在控制器中设置默认参数值，则如下所示

// GET api/products
[HttpGet]
public IEnumerable<Product> Get(int count = 50)

    Conn mysqlGet = new Conn(_connstring);
    return mySqlGet.ProductList(count);

【参考方案3】：

这适用于 ASP.net MVC5，代码对 .Net Core 无效

1- 定义一个自定义属性如下

public class SwaggerDefaultValueAttribute: Attribute

   public SwaggerDefaultValueAttribute(string param, string value)
   
      Parameter = param;
      Value = value;
   
   public string Parameter get; set;
   public string Value get; set;

2- 定义一个 Swagger OperationFilter 类

public class AddDefaulValue: IOperationFilter

   void IOperationFilter.Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
   
      if (operation.parameters == null || !operation.parameters.Any())
      
         return;
      
      var attributes = apiDescription.GetControllerAndActionAttributes<SwaggerDefaultValueAttribute>().ToList();

      if (!attributes.Any())
      
         return;
      
      
      foreach(var parameter in operation.parameters)
      
         var attr = attributes.FirstOrDefault(it => it.Parameter == parameter.name);
         if(attr != null)
         
            parameter.@default = attr.Value;
         
      
    

3- 在 SwaggerConfig 文件中注册 OperationFilter

c.OperationFilter<AddDefaultValue>();

4- 用属性装饰你的控制器方法

[SwaggerDefaultValue("param1", "AnyValue")]
public HttpResponseMessage DoSomething(string param1)

   return Request.CreateResponse(HttpStatusCode.OK);

【讨论】：

很好，但你能告诉我如何将它用于多个参数吗？编辑：将 [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] 添加到属性类。

【参考方案4】：

在 YAML 文件中，您可以定义需要哪些属性。此示例来自 NSwag 配置。

/SearchPendingCases:
    post:
      summary: Search pending cases
      description: Searches for pending cases and orders them
      parameters:
        - in: body
          name: SearchQuery 
          required: true
          schema:
            type: object
            required:
              - OrderBy
              # do not include OrderDirection here because it is optional
            properties:
              OrderBy:
                description: Name of property for ordering
                type: string
                # you can remove the following two lines 
                # if you do not want to check the string length
                minLength: 1    
                maxLength: 100
              OrderDirection:
                description: Optional order direction, default value: Descending
                type: string
                enum: [Ascending, Descending] # valid enum values
                default: Descending           # default value

Swagger - Enums

Swagger - Unlocking the Spec: The default keyword

【讨论】：

也许我应该明确说明，但我实际上有 Swashbuckle.AspNetCore 库生成的 swagger 文档，这是官方推荐的 asp.net core docs

对不起，我不熟悉这个库:(