Learn how to add the Swashbuckle package to your REST-based API to automatically generate a Swagger descriptor for use with the REST broker. This approach works when you control the source of your API. If you do not control the source and are simply referencing an existing API (typically online), you must use a different approach. See Resources for Working with the REST Service Broker for more information.

Table of Contents

This article contains the following sections:

About Swagger

Swagger is a representation of your RESTful API. With a Swagger-enabled API, you get interactive documentation, client SDK generation, and discoverability. You also get a descriptor file that you can use with the REST broker which, in turn, can be used to generate SmartObjects for your API.

Installing Swashbuckle and adding it to your Project

Swashbuckle is the NuGet.org package that you add to your new or existing API. Download the Swashbuckle package

Instead of adding Swashbuckle to an existing API, you can try a new API example from Microsoft by following the MSDN article Getting Started with ASP.NET Web API 2 (C#)

When the package is downloaded, use the package manager console to install it using the following command:

PM>INSTALL-PACKAGE SWASHBUCKLE –VERSION 5.5.3

Your version number in the command line depends on the version you've downloaded.

After the package is installed, go to the App_Start folder in the Solution Explorer. You'll notice a new file called SwaggerConfig.cs. This file is where you enable Swagger and set configuration options.

Image

Enabling Swagger Doc and UI

The first thing you have to do to enable Swagger is to add the following line. This enables the Swagger file generation and the Swagger UI to test your API.

GlobalConfiguration.Configuration
.EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API")) .EnableSwaggerUi();

Start a new debugging session (F5) and navigate to:

http://localhost:[PORT_NUM]/swagger

You see Swagger UI help pages for your APIs.

Image

Expanding an API and clicking the Try it out! button makes a call to that specific API and returns results.

Image

Image

Enabling Swagger to use XML Comments

To add more metadata to your Swagger file, configure Swashbuckle to use XML comments. These are the same XML comments that ASP.NET Help Pages use.

First, enable the creation of XML documentation. In the Solution Explorer, right-click the Web API project and click Properties. Click the Build tab and navigate to Output. Make sure that the XML documentation file option is checked. You can leave the default file path.

Image

Next, you need to configure Swashbuckle to include the XML comments in the Swagger metadata. Add the following line to SwaggerConfig.cs. Make sure to change the file path to the path of your XML documentation file.

c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));

Finally, if you haven't already, add XML comments to your Models and API methods. 

Image

Image

Run the project and navigate to the Swagger file by adding /swagger to your URL. You should see more details added to your API documentation as highlighted.

Image

Under Response Class click Model. You see your XML comments added to your models.

Image

Describing Enumerations as Strings

When you have a class containing an enum property, in this case called Universe, Swagger displays these Enum values as their integer value. This is not useful and can be changed to display the string representation of the enumeration.

Image

Add the following line to SwaggerConfig.cs:

c.DescribeAllEnumsAsStrings();

The complete configuration up to this point:

GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "SwaggerDemoApi");
c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML",
System.AppDomain.CurrentDomain.BaseDirectory));
c.DescribeAllEnumsAsStrings();
})
.EnableSwaggerUi();

The XML comments are now used for enumerations:

Image

This is one example of the options you have with Swashbuckle. Use the project site to learn more about the various options Swashbuckle offers.

Getting the Swagger JSON File

To see the actual Swagger file, navigate to the URL that is in the header of the Swagger UI documentation page.

Image

Using the Swagger File with the REST Broker

The Swagger file can be used in the Descriptor Location field when registering a REST broker service instance which, in turn, is for generating SmartObjects based on your API. For more information about the REST broker, see the Help topic REST Service Broker