Swashbuckle and Swagger for .NET Core 1.0 validator issue

I’ve decided to write this blog post when I came across an issue with Swashbuckle trying to validate JSON file in Swagger and was failing since Swagger’s online validator was trying to fetch JSON file from an development server which is not accessible from external networks.

The Swashbuckle and Swagger problem

The project was .NET Core RESTful WebAPI and was using Swashbuckle v6.0.0-beta902. The issue mentioned above was not a big deal and everything was working, however being perfectionist I wanted to keep application as clean as possible. After quick research I’ve realized that I needed to disable Swagger Validator, however couldn’t find a Swagger’s option in Swashbuckle… After a few minutes of reasearchining more I noticed there is a .NET Core nuget package for Swashbuckle that was released on 3rd of January this year, and should do the trick. So I’ve removed existing package and started with a fresh install of Swashbuckle.

Sample project set up

To illustrate this better (with less irrelevant code), I’ve created a new .NET Core WebAPI solution. First, run following command to install Swashbuckle for ASP .NET Core.

Install-Package Swashbuckle.AspNetCore -Pre

Next, in Startup class add Swagger Generator middleware in your ConfigureServices() method. I’ve also added basic information about my API.

public void ConfigureServices(IServiceCollection services)
{
   services.AddSwaggerGen(c =>
   {
      c.SwaggerDoc("v1", new Info
      {
         Title = "My API",
         Version = "v1"
      });
   });

   services.AddMvc();
}

And finally, let’s configure Swagger and it’s UI in Configure() method. I’ve specified custom “swagger/ui” route prefix (optional), added one info endpoints, and disabled validator. Code snippet below.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    app.UseMvc();

    app.UseSwagger();
    app.UseSwaggerUi(c =>
    {
        // keeping swagger UI URL consistent with my previous settings
        c.RoutePrefix = "swagger/ui";
        // adding endpoint to JSON file containing API endpoints for UI
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
        // disabling the Swagger validator -- passing null as validator URL.
        // Alternatively, you can specify your own internal validator
        c.EnabledValidator(null);
    });
}

That was it! Now if you launch your WebAPI, and navigate http://localhost:58250/swagger/ui (port might be different), you will see a beautiful Swagger interface with all your API endpoints.

Gotchas

• RoutePrefix must not start with a slash “/”.
• However, SwaggerEndpoint must start with an endpoit.
• If you use a virtual director in your URL, you need to specify that in SwaggerEndpoint().
• Method parameters that are not part of the route types might need to have an attribute explicitly defining where the data should come from, if you are getting 500 error on accessing Swagger’s JSON info file. E.g. [FromQuery] adding for a parameter that comes from query string.

[HttpGet("{id}")]
public string Get(int id, [FromQuery] DateTime? dateTime)
{
    return "value";
}

Summary

Swashbuckle adds an automatically generated Swagger UI for API endpoints in .NET Core projects. It’s very easy and quick to set up and updates endpoint information automatically.

Swashbuckle documentation with other options can be found here.