将查询字符串参数添加到我的Swagger规范中 [英] Adding Query String Params to my Swagger Specs

问题描述

我在我的Web API中使用Swashbuckle(C#中的wagger).我有几个返回列表的GET端点，并且允许用户向QueryString中添加一个perpage和page参数

I am using Swashbuckle (swagger for C#) with my Web API. I have several GET End-Points that return lists and I allow the user to add a perpage and page params into the QueryString

示例: http://myapi.com/endpoint/?page=5&perpage = 10

我看到swagger支持'query'中的参数，但是如何让Swashbuckle做到这一点?

I see that swagger does support parameter in 'query' but how do I get Swashbuckle to do it?

我在其中一项评论中提到，我通过创建自定义属性来允许我做所需的事情来解决了我的问题.下面是我的解决方案的代码:

I mention in one of the comments that I solved my issue by creating a custom attribute to allow me to do what I needed. Below is the code for my solution:

[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配置注册属性:

Register the Attribute with the Swagger Config:

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

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

Then add this attribute to your methods:

[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)]

推荐答案

您可以轻松实现.假设您有一个 ItemsController ，其操作如下:

You can achieve that quite easily. Suppose you have an ItemsController with an action like this:

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

Swashbuckle将生成此规范(仅显示相关部分):

Swashbuckle will generate this specification (only showing relevant part):

"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 时，只需将参数设为不可为空.

When you want page and perpage to be required, just make the parameters not nullable.

这篇关于将查询字符串参数添加到我的Swagger规范中的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！