20

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

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

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

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)]
Improve this question
2
  • 2
    Where does SwaggerParametersAttributeHandler come from? :s Commented Oct 31, 2017 at 21:27
  • Darn, apparently the ParameterType enum is also missing. Any chance you'd be willing to fill in the blanks for us? :D Commented Oct 31, 2017 at 21:40

4 Answers 4

Reset to default
14

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 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"
           }
        ]
     }
  }

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

Improve this answer
Sign up to request clarification or add additional context in comments.

8 Comments

That is a very reasonable answer but I ended up creating a custom Swagger Attribute to handle it
How did you achieve that @JasonH? Are sources online that can point to a solution like you have mentioned?
The code I was working on is not owned by myself so I did not share the attribute I created. I can edit my original question with what I did so you can see.
Sorry, you are right, I forgot an important part. You have to register the attribute with the Swagger Configuration. I have edited my original post to show this.
@JasonH I got it figured it. The clue was the operation filter thanks!. I have it auto adding query param text boxes to my docs now by decorating the controller methods. Ill post my solution as an answer to your question later so that other people can benefit from this solution. Thanks again!
|
6

Here is a summary of the steps required (ASP.Net Core 2.1, Swashbuckle.AspNetCore v4.0.1) for the Attribute method. I needed a parameter starting with "$" so optional parameters were not an option!

SwaggerParameterAttribute.cs

     [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 string DataType { get; set; }
        public string ParameterType { get; set; }
        public string Description { get; private set; }
        public bool Required { get; set; } = false;
    }

SwaggerParameterAttributeFilter.cs

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;
public class SwaggerParameterAttributeFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        var attributes = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
            .Union(context.MethodInfo.GetCustomAttributes(true))
            .OfType<SwaggerParameterAttribute>();

        foreach (var attribute in attributes)
            operation.Parameters.Add(new NonBodyParameter
            {
                Name = attribute.Name,
                Description = attribute.Description,
                In = attribute.ParameterType,
                Required = attribute.Required,
                Type = attribute.DataType
            });              
    }
}

add this in Startup.ConfigureServices

 using Swashbuckle.AspNetCore.Swagger;
 services.AddSwaggerGen(c =>
 {
      c.OperationFilter<SwaggerParameterAttributeFilter>();
      c.SwaggerDoc("v1.0", new Info { Title = "My API", Version = "v1.0" });
 });

and use like this:

[SwaggerParameter("$top", "Odata Top parameter", DataType = "integer", ParameterType ="query")]

DataTypes can be: integer, string, boolean

ParameterTypes: can be path, body, query

Improve this answer

Comments

2

I know this is old and all but I spent some time looking for the easier method and found it. So for anyone who also stumbles onto this old thread, here it is:

public async Task<IActionResult> Foo([FromQuery]YourDtoType dto)
Improve this answer

1 Comment

This is exactly what OP is looking for, needs to be top answer
0

There's some comments here regarding missing information on the SwaggerParametersAttributeHandler. It is an operation filter to help you determine what to do to your attributes.

Here's an example handler I used that allows me to override nullable parameters' required fields using the 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<SwaggerParameterAttribute>();

        if (operation.parameters == null)
        {
            operation.parameters = new List<Parameter>();
        }

        // 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;
            }
        }
    }
}
Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.