SwashBuckle Swagger-UI Example Request for HTTP GET Method with FromQuery Attribute

Question

I've managed to add examples to my Web API with SwashBuckle.AspNetCore and Swashbuckle.AspNetCore.Filters for POST methods:

DTO

public class ExampleDTO
{
    public string MyFoo { get; set; }
}

Example Request

public class ExampleDTOExample : IExamplesProvider<ExampleDTO>
{
    public ExampleDTO GetExamples()
    {
        return new ExampleDTO()
        {
            MyFoo = "bar"
        };
    }
}

Controller Method

[SwaggerOperation(
    Summary = "...",
    Description = "...",
    OperationId = "PostFoo"
)]
[SwaggerResponse(200, "Returns ...", typeof(int))]
[HttpPost]
[Route("post-foo")]
public ActionResult<int> PostFoo([FromBody]ExampleDTO request)
{
    throw new NotImplementedException();
}

This work perfectly fine. When I click the "try it out" button, I have "bar" as prefilled value for the property foo.

However, when I'm trying to do the same for a GET request, e.g., with parameters from query like this, the text box is not prefilled with the value "bar":

public class ExampleDTO
{
    [FromQuery(Name = "foo")]
    public string MyFoo { get; set; }
}

Controller Method

[SwaggerOperation(
    Summary = "...",
    Description = "...",
    OperationId = "GetFoo"
)]
[SwaggerResponse(200, "Returns ...", typeof(int))]
[HttpGet]
[Route("get-foo")]
public ActionResult<int> GetFoo([FromQuery]ExampleDTO request)
{
    throw new NotImplementedException();
}

How can I force the text box to be prefilled with the example value? So far I've found a solution for specifying a default value which is not want I want. I only want to use attributes for a default value in Swagger UI.

Answer 1

If I'm not mistaken the value you see on:

That is not the example but the default value.

---

Here is something that I've done in the past:

"/attrib/{payId}": {
    "get": {
        "tags": [
            "Attribute"
        ],
        "operationId": "Attribute_Get",
        "consumes": [],
        "produces": [
            "application/json",
            "text/json",
            "text/html"
        ],
        "parameters": [
            {
                "name": "payId",
                "in": "path",
                "required": true,
                "type": "integer",
                "format": "int32",
                "default": 123
            }
        ]

http://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=Attribute#/Attribute/Attribute_Get

---

Here is another case with both default and example

"Company": {
    "required": [
        "Id",
        "MyId"
    ],
    "properties": {
        "Id": {
            "description": "The Unique Company ID",
            "example": "123",
            "type": "integer",
            "format": "int32",
            "default": 456
        },
        "MyId": {
            "example": 123,
            "type": "integer",
            "format": "int32"
        },

http://swagger-net-test.azurewebsites.net/swagger/ui/index#/Company/Company_Get2

You can see that the example is not what is shown in the Swagger UI

Answer 2

You can use XML comments for this purpose.

Since May 2018, Swashbuckle.AspNetCore supports adding examples via XML comments.

Source: https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters/blob/master/README.md#request-example

But firstly, you enable XML Documentation file for your project. You can enable it in project's properties.

After you must include XML comments to Swagger in Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddSwaggerGen(c =>
    {
        ...

        // This path can be different on your project.
        var filePath = Path.Combine(AppContext.BaseDirectory, "WebApi.xml");
        c.IncludeXmlComments(filePath);

        ...

    });

    ...
}

After, you must add XML example to DTO's property

public class ExampleDTO
{
    /// <example> MyFooExampleValue </example>
    public string MyFoo { get; set; }
}

Result is like as below:

"Try it out"'s result:

---

Note: Not only in the DTO, you can also write XML comment directly to the API

And soon (April 2020, once my Swashbuckle.AspNetCore PR has been released) you'll be able to add examples for primitive types on the querystring too, e.g.

/// <param name="id" example="123">The product id</param>
[HttpGet("{id}")]
public Product GetById(int id)

---

For more information you can visit these links:

Using XML Comments As Web API Documentation With Swagger

Request example of Swashbuckle.AspNetCore.Filters