Swagger and Swashbuckle: Disable Try It Out

In last week’s post, I walked through adding Swagger support to an ASP.NET Core 2 API using the Swashbuckle. One of the awesome things about Swashbuckle is it provides an integration with swagger-ui.

Try it out!

One of the features of the UI integration is the ability to invoke an end point using the “Try it out!” button. This feature is awesome during development but may not be something you want to allow, depending on the use case, for a production end point.

Disable Try it out!

I tried googling lots of different things to find the option to disable the “Try it out” button and had a really hard time finding an answer. It didn’t help that I want the button text to be “Try it now” for some reason. Thankfully it truly was a failure on my part and there is a provided way to disable “Try it out” and it is much more flex able than what I was initially looking for.

In the  Configure function of the  Startup class find the call to  app.UseSwaggerUI. Adding  c.SupportedSubmitMethods(new string[] {}); will completely disable “Try it out”. The following is the full call to  app.UseSwaggerUI just to provide context.

The great thing about the way this is set up if you can allow some actions and not others. For example, say you wanted to allow get actions but disable the rest. The following would allow for that.

One word of caution the above is case sensitive and if you use  Get instead of  get “Try it out” will remain disabled.

Swagger and Swashbuckle with ASP.NET Core 2

This post is going to be very similar to a post from last December which can be found here. A lot has changed since then and this post is going to add Swagger to an existing ASP.NET Core application using Swashbuckle much like the one from last year. The starting point of the code can be found here.

What is Swagger?

Swagger is a specification used to document an API. As I am sure we all know API documentation tends to get out of date fast and a lot of times is a low priority.  Swagger aims to help solve that problem using a format that is both human and machine readable which can be maintained in either JSON or YAML. The documentation can be auto generated using a tool like Swashbuckle which provides away to keep your consumers up to date. Check out this post by the Swagger team for the full introduction.

What is Swashbuckle?

Swashbuckle provides auto generation of Swagger 2.0, a UI, etc. The project takes all the pain out of getting going with Swagger as well as providing tools and hooks for using and customizing Swagger related items. The full description can be found here.

Adding Swashbuckle

Using your favorite method of NuGet interaction, add the  Swashbuckle.AspNetCore NuGet package to your project. Personally, I have gotten where I edit the csproj file to add new packages. If that is your style you would need to add the following package reference.

This one package provides all the functionality we will need.

Wiring up Swashbuckle

Now that the Swashbuckle package is installed, there are a few changes that are needed in the  Startup class to get everything wired up. First, in the  ConfigureServices function, the Swagger generator needs to be added to DI.

AddSwaggerGen allows for configuration of options, but here we are just setting a name and a minimal amount of information.

In the  Configure function Swagger needs to be added to the request pipeline in order to expose the Swagger generated data. I placed this after  UseMvc.

At this point, the Swagger generated JSON would be available at  {yourBaseUrl}/swagger/v1/swagger.json. To take a step further let’s expose the UI that comes with Swashbuckle. Add the following just below  app.UseSwagger().

Now a UI based on your API is available at  {yourBaseUrl}/swagger with zero extra work on your part. The following is the UI for the post contact route in the example project.

As you can see the UI provides a great view of your API as well as ways to try it out and the potential responses that should be expected from a call.

Controller Considerations

All of this wonderful functionality doesn’t come for free of course. In order for Swashbuckle to pick up your routes, your controller will need to use attribute based routing instead of depending on convention based routing.

In order for Swashbuckle to know the return types and of your controller actions may need to have some attributes added. This won’t be required if your action return a specific type, but if you are returning an  IActionResult you should attribute your action with all the  ProducesResponseType you need to cover the results of your action. For example, the following is the action definition for the Post in the screen shot above.

Wrapping up

Swashbuckle makes it easy to add Swagger to a project. I feel that it also provides a huge value for anyone trying to consume an API. It is of course not a magic bullet and communication with your API consumers about API changes will still be critical.

Microsoft’s docs have a great walk through which can be found here. It does more in-depth on customizing your setup and as far as modifying the look of the UI. I also recommend checking out the GitHub page for the project which can be found here.

The finished code can be found here.

Swagger and Swashbuckle with ASP.NET Core API

This post is going to walk through adding Swagger to an existing ASP.NET Core API application using Swashbuckle. The starting point for the code can be found here.

What is Swagger?

Swagger is a specification on documentation an API. As I am sure we all know API documentation tends to get out of date fast and a lot of times is a low priority.  Swagger aims to help solve that problem using a format that is both human and machine readable which can be maintained in either JSON or YAML and can be auto generated using a tool like Swashbuckle. Check out this post by the Swagger team for the full introduction.

What is Swashbuckle?

Swashbuckle provides auto generation of Swagger 2.0, swagger-ui integration, etc. The project takes all the pain out of getting going with Swagger as well as providing tools and hooks for using and customizing Swagger related items. The full description can be found here.

Adding Swashbuckle to the project

There are lots of ways to get a new package into an ASP.NET Core application and the following covers the NuGet UI, Package Manager Console and Project.json. Pick one of them to use.

NuGet UI

Right click on the project Swashbuckle is going to be added to, Contacts in the case of the sample code, and select Manage NuGet Packages.

swashbuckleprojectmenu

Select the Browse tab, check the Include prerelease checkbox and search for Swashbuckle. Prerelease is need to get the version that works with ASP.NET Core.

swashbucklenuget

Finally click the Install button and work though any confirmation dialog screens that might show.

Package manager console

From the package manager console run  Install-Package Swashbuckle -Pre.

Project.json

Open porject.json and in the  dependencies section add  "Swashbuckle": "6.0.0-beta902".

Add and configure Swashbuckle

In the  ConfigureServices function of the  Startup class add the following. I added it as the end, but placement shouldn’t matter.

Next in the  Configure function after  app.UseMvc add the following.

The first line enable serving of the Swagger JSON endpoint and the second enables the swagger-ui.

Test it out

Running the application will now provide two new routes one or each of the items added to the  Configure function above.

The first is  http://localhost:13322/swagger/v1/swagger.json (your base URL may differ if not using the sample procject) and it exposes the Swagger compliant JSON.

The second URL is  http://localhost:13322/swagger/ui and it provides a very readable view of the documented API along with examples and options to try the API out. The following as an example of what the current version outputs.

swaggeruiexample

Wrapping up

Swashbuckle make it easy to add Swagger to a project. I feel that it also provides a huge value for anyone trying to consume an API. It is of course not a magic bullet and communication with your API consumers about API changes will still be critical.

Microsoft’s docs has a great walk through which can be found here. It does more in-depth on customizing your setup and as far as modifying the look of the UI.

The code for this post in it’s finished state can be found here.