将查询字符串参数添加到我的Swagger规范中

我使用我的Web API使用Swashbuckle（swagger for C＃）。 我有几个返回列表的GET端点，我允许用户在QueryString中添加perpage和page params

示例： http ： //myapi.com/endpoint/？page = 5＆pagepage = 10

我看到swagger在’query’中确实支持参数但是我如何让Swashbuckle去做呢？

---

我在其中一条评论中提到我通过创建自定义属性来解决我的问题，以便让我做我需要的事情。 以下是我的解决方案的代码：

[AttributeUsage(AttributeTargets.Method, Inherited = false, AllowMultiple = true)] public class SwaggerParameterAttribute : Attribute { public SwaggerParameterAttribute(string name, string description) { Name = name; Description = description; } public string Name { get; private set; } public Type DataType { get; set; } public string ParameterType { get; set; } public string Description { get; private set; } public bool Required { get; set; } = false; } 

使用Swagger配置注册属性：

 GlobalConfiguration.Configuration .EnableSwagger(c => { c.OperationFilter(); }); 

然后将此属性添加到您的方法：

 [SwaggerParameter("page", "Page number to display", DataType = typeof(Int32), ParameterType = ParameterType.inQuery)] [SwaggerParameter("perpage","Items to display per page", DataType = typeof(Int32), ParameterType = ParameterType.inQuery)] 

Answer 1

你可以很容易地实现这一点。 假设你有一个ItemsController ，其动作如下：

 [Route("/api/items/{id}")] public IHttpActionResult Get(int id, int? page = null, int? perpage = null) { // some relevant code return Ok(); } 

Swashbuckle将生成此规范（仅显示相关部分）：

 "paths":{ "/api/items/{id}":{ "get":{ "parameters":[ { "name":"id", "in":"path", "required":true, "type":"integer", "format":"int32" }, { "name":"page", "in":"query", "required":false, "type":"integer", "format":"int32" }, { "name":"limit", "in":"query", "required":false, "type":"integer", "format":"int32" } ] } } 

如果需要page和perpage ，只需使参数不可为空。

Answer 2

这里有一些关于SwaggerParametersAttributeHandler缺失信息的评论。 它是一个操作filter，可帮助您确定如何对属性执行操作。

这是我使用的一个示例处理程序，它允许我使用SwaggerParameterAttribute覆盖可空参数的必填字段。

 public class RequiredParameterOverrideOperationFilter : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { // Get all SwaggerParameterAttributes on the method var attributes = apiDescription.ActionDescriptor.GetCustomAttributes(); if (operation.parameters == null) { operation.parameters = new List(); } // For each attribute found, find the operation parameter (this is where Swagger looks to generate the Swagger doc) // Override the required fields based on the attribute's required field foreach (var attribute in attributes) { var referencingOperationParameter = operation.parameters.FirstOrDefault(p => p.name == attribute.Name); if (referencingOperationParameter != null) { referencingOperationParameter.required = attribute.Required; } } } }