Using Swashbuckle in ASP.NET Core 1.0

I spend a lot of time writing APIs in .NET. As part of that, I have to document my endpoints. Being the lazy developer I am, I always want this documentation generated for me so I never need to lift a finger after I add a new API.

In the past, Microsoft’s ASP.NET Web API Help Pages. While they were a bit ugly by default, and did not have built in support for testing the API, they worked and did the job that I asked of them.

Recently, I have been working very heavily in ASP.NET Core 1.0. While it is a fast-moving project, and things are changing almost daily, it is a lot of fun and it feels good to work with. (It may also have something to do with the lightweight and familiar tooling that I am using while developing on OSX. I love that!) Unfortunately, the Web API Help Pages have not been ported to support ASP.NET Core. So, I went in search of another alternative.

Very quickly, I landed on Swashbuckle which adds Swagger documentation, and a UI to browse said documentation. It supports the testing of API endpoints, the model is easier to understand, and it looks great! Everything I could want.

Of course, given that I’m working with ASP.NET Core, the documentation to specifically bring Swashbuckle into my project was a little lacking given the rapid changes happening to Core. So, I wanted to document what I found here. Please note that this is the way it is currently performed, and it may change again sometime in the future. Also note that I am doing this from Release Candidate 1 - I have not yet switched over to 2.

First, you must add the package reference to project.json. (Don’t get me started on project.json not being a thing anymore…)

"Swashbuckle": "6.0.0-*"

Once you have done this, crack open Startup.cs and add the following configuration to the ConfigureServices() method:

// Add Swagger documentation.
services.AddSwaggerGen();
services.ConfigureSwaggerDocument(options => {
    options.SingleApiVersion(new Info {
        Version = "v1",
        Title = "My API",
        Description = "This is my API.",
        TermsOfService = ""
    });
});
services.ConfigureSwaggerSchema(options => {
    options.DescribeAllEnumsAsStrings = true;
});

Of course, configure schema options and other items as you see fit.

Then, also in Startup.cs, add these two lines to Configure().

app.UseSwaggerGen();
app.UseSwaggerUi();

Go ahead and run your project! You should now be able to access your documentation at http://localhost:5000/swagger/ui/index.html. Of course, adjust the URL accordingly.

As an addition, I wanted to hide two of my APIs as they are not properly wired up. Per this Github issue, Swashbuckle is built on Web API’s built-in metadata layer. This is beautiful because you can then use the ApiExplorerSettingsAttribute to ignore endpoints, like this:

[ApiExplorerSettings(IgnoreApi=true)]
public class MyController : Controller
{
  // ...
}

Note that you can use these on an entire controller, or on individual endpoints.

That’s all there is to it! You now have beautiful documentation for all to use.

comments powered by Disqus