SwaggerRequestExample attribute does not work in ASP.NET MVC 5 (.NET Framework 4.5.2)

Question

I am toying with Swashbuckle.Examples package (3.10.0) in an ASP.NET MVC project. However, I cannot make request examples appear within the UI.

Configuration (SwaggerConfig.cs)

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration
        .EnableSwagger(c => {
             c.SingleApiVersion("v1", "TestApp.Web");
             c.IncludeXmlComments(string.Format(@"{0}\bin\TestApp.Web.xml", System.AppDomain.CurrentDomain.BaseDirectory));
             c.OperationFilter<ExamplesOperationFilter>();
             c.OperationFilter<DescriptionOperationFilter>();
             c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
                })
            .EnableSwaggerUi(c => { });
 }

Request example classes

public class EchoRequestExample : IExamplesProvider
{
    public object GetExamples()
    {
        return new EchoInput { Value = 7 } ;
    }
}

public class EchoInput
{
    public int Value { get; set; }
}

Action

[HttpGet]
[Route("Echo")]
[CustomApiAuthorize]
[SwaggerRequestExample(typeof(EchoInput), typeof(EchoRequestExample))]
[ResponseType(typeof(EchoServiceModel))]
public HttpResponseMessage Echo([FromUri] EchoInput model)
{
    var ret = new EchoServiceModel
    {
        Username = RequestContext.Principal.Identity.Name,
        Value = value
    };
    return Request.CreateResponse(HttpStatusCode.OK, ret);
}

Swagger UI shows xml comments and output metadata (model and an example containing default values), but shows no request example. I attached to process and EchoRequestExample.GetExamples is not hit.

Question: How to make SwaggerRequestExample attribute work in ASP.NET MVC 5?

Note: Windows identity is used for authorization.

score 1 · Answer 1 · answered Aug 02 '18 at 19:31

1

I received an answer from library owner here:

Swagger request examples can only set on [HttpPost] actions

It is not clear if this is a design choice or just a limitation, as I find [HttpGet] examples also relevant.

answered Aug 02 '18 at 19:31

Alexei - check Codidact

22,016
16
145
164

He is right! Officially (per the OpenApi Specification 2.0) there are no examples on the get... but for a while now everyone has been using `x-example` just like I showed in my answer – Helder Sepulveda Aug 02 '18 at 21:58

score 0 · Accepted Answer · answered Aug 02 '18 at 12:40

0

I know the feeling, lot's of overhead just for an example, I struggle with this for a while, so I created my own fork of swashbuckle, and after unsuccessful attempts to merge my ideas I ended up detaching and renaming my project and pushed to nuget, here it is: Swagger-Net

An example like that will be:

    [SwaggerExample("id", "123456")]
    public IHttpActionResult GetById(int id)
    {

Here the full code for that: Swagger_Test/Controllers/IHttpActionResultController.cs#L26

Wondering how that looks like on the Swagger-UI, here it is:
http://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=IHttpActionResult#/IHttpActionResult/IHttpActionResult_GetById

answered Aug 02 '18 at 12:40

Helder Sepulveda

15,500
4
29
56

I do not mind the overhead since my goal is to provide a list of examples. However, did you manage to make it work using Swashbuckle.Examples? I will try your library anyway. – Alexei - check Codidact Aug 02 '18 at 13:11
On my library I merged most of the functionality provided by Swashbuckle.Examples, if there is something I'm missing that you need let me know and I can add it. – Helder Sepulveda Aug 02 '18 at 13:43
I think `SwaggerRequestExample` is missing. While it requires more code, it provides a way to specify a dynamic list of examples. – Alexei - check Codidact Aug 02 '18 at 13:49
SwaggerExample should do what you need instead of SwaggerRequestExample – Helder Sepulveda Aug 02 '18 at 13:50
It seems that `SwaggerRequestExample ` is messed up also on [ASP.NET Core](https://stackoverflow.com/questions/46875059/swaggerrequestexample-is-being-ignored) – Alexei - check Codidact Aug 02 '18 at 13:50
Look at my test: http://swagger-net-test.azurewebsites.net/swagger/ui/index in there you should find simple, complex examples, default values, descriptions with markup, parameters with regex, max and min... let me know if you need something specific – Helder Sepulveda Aug 02 '18 at 13:55
@LarsTech why don't you ask a proper question here on StackOverflow instead of adding a comment? – Helder Sepulveda Nov 24 '21 at 20:28

SwaggerRequestExample attribute does not work in ASP.NET MVC 5 (.NET Framework 4.5.2)

2 Answers2

Linked