Swagger 參數的默認值

Question

如何在從以下 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

Answer 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

更新

在對評論的討論之后，我更新了Swagger-Net以通過反射讀取DefaultValueAttribute這是我正在使用的示例類：

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

這是 swagger 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

Answer 2

如果您可以在控制器中執行此操作，則設置默認參數值的工作方式如下

// GET api/products
[HttpGet]
public IEnumerable<Product> Get(int count = 50)
{
    Conn mySqlGet = new Conn(_connstring);
    return mySqlGet.ProductList(count);
}

Answer 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);
}

Answer 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 - 枚舉

Swagger - 解鎖規范：默認關鍵字