Swagger In .NET
Multiple example for parameters in Swagger with ASP.NET Core
A Short guide on how to add multiple example of route parameter in swagger doc.
In one of my previous swagger related post, I have describe how can we create multiple examples for request and response body. In this post I am going to explore how can we do the same with route parameters.
Let’s start..
Let’s say we have one Get endpoint which takes a route parameter.
and when we generate swagger document we get following on swagger UI.
Every time we have to call the API, we need to put the value and call the API.
In some case, we want to put some example value so that we don’t need to put it manually or that user is aware what kind of value is expected.
We can make use of xml comments feature along with swashbuckle to generate example along with definition.
so we make changes to IncludeXmlComments in the swagger document.
and also added xml comments to the API.
Now we get example also.
Great.. now we can try without entering anything manually. it will take example value and execute the API.
This works great for single example but in some case we want to define more then one example so that user is aware what all values are possible. also couple stackoverflow question were also asked in same direction so I thought let me try and see how can we achieve this.
first thing I tried using xml comments itself. so I changed the example tag to have multiple values. like below
/// <param name="limit" example="[2,10]"></param>and when I ran the app , I get the following in swagger UI.
It included all the values as list but I can’t execute API, as it is expecting a single integer not the list.
I also searched if this is supported by OpenAPI Specification and Swagger UI in general or not and I found a link that it provides example of it.
https://swagger.io/docs/specification/adding-examples/
so then next, I searched swashbuckle documentation and source code for such support but couldn’t find anything.
Solution
As I could not found anything, I decided to try out my self by adding the examples to parameters.
I didn’t wanted to touch the xml part so I decided to use another approach.
for example, I would decorate my parameter with example values like below.
[SwaggerParameterExample("Max", "10")]int limitSo that I see a named example “Max” on swagger UI with value “10”
Something like below.
Let’s see what changes are required to make it work like this.
we will start with defining the attribute class. “SwaggerParameterExampleAttribute.cs”
and then we create a “CustomParameterFilter”
and add that filter to swagger configuration in AddSwaggerGen().
builder.Services.AddSwaggerGen(c= > c.ParameterFilter<CustomParameterFilter>());and last part is to decorate any parameter with attribute.
Note that I have removed example from xml comments to avoid any confusion.
Now when we ran our API and check on swagger we get following page
Another Example
Let’s take another example where I take model as an parameter to API.
I have modified the API to take Model as a parameter. and we can define examples inside the model definition.
You can see, for Limit I have defined two examples and also added one more property of string type with only value.
With only these changes let’s run our API again and look at the swagger UI.
We can see now both parameters are showing the examples values as we have defined and we can select from the list whichever we want to use for execution.
One more point, as we have defined the examples, it does not mean that we can’t give any other value. these are just predefined values which gets filled when we select from dropdown. we can very well put any other values we want. and guess what swaggerUI also displays that as “[Modified value]”.
and this will be available as long as we don’t refresh the swagger UI.
Summary
In this short tutorial, we have seen how we can set multiple example for parameter in route.
Hope it is helpful.
Happy coding and keep learning..!
