Embed Swagger UI into Existing .NET APIs

Use Swashbuckle to automatically generate a valid Swagger/OpenAPI 2.0 Specification and integrate Swagger UI into your existing .NET APIs.

Swashbuckle is an open source library that allows you to embed Swagger UI into your existing .NET APIs. Available as a NuGet Package, the Swashbuckle installation embeds swagger-ui directly into your project. It also includes a configuration class to customize your Swagger UI settings.

Swashbuckle will automatically generate a valid Swagger/OpenAPI 2.0 Specification based on your existing routes, controllers, models, and custom settings. Swagger UI uses this OpenAPI Specification to generate your API's documentation, available from your API's root URL (e.g., http://localhost:50200/swagger/ui/index).

This tutorial applies only to existing .NET APIs that are hosted in IIS. It will guide you through the process of installing Swashbuckle and enabling XML comments for your Swagger UI documentation. For a complete list of features and installation options for self-hosted APIs, refer to the Swashbuckle README on GitHub.com.

Step 1: Install Swashbuckle from NuGet.

To install the latest stable version of Swashbuckle from the NuGet Package Console, type the following:

Install-Package Swashbuckle

To install Swashbuckle from the NuGet Package Manager:

  1. Open your existing .NET API in Visual Studio. From the Solution Explorer, right click your Project name and select Manage NuGet Packages...
  2. From the NuGet Package manager, click Browse, and search for swashbuckle. Select the latest stable version, then click Install. Your installation progress will be displayed in the Output Window. Visual Studio may prompt you with an installation summary. Click OK to continue.

When the installation is complete, you can immediately browse your Swagger UI documentation.

Step 2: Browse your new Swagger UI documentation.

To browse your Swagger UI documentation:
  1. Build and run your API.
  2. From your browser, navigate to http://[localhost:50200]/swagger/ui/index.
On your documentation home page, all of your endpoints should be listed and grouped by each of your controller(s). Every time you re-build your API, your Swagger UI documentation will automatically reflect any changes.

Step 3: Add XML comments.

To include XML comments in your Swagger UI documentation, you'll need to enable your API's XML Output settings and update the Swashbuckle configuration class.
  1. Right click your API Project from the Solution Explorer and select Properties.
  2. From the Properties window, click Build, and locate the Output section. Make sure that XML documentation file is checked, and copy your XML file path to a text file for later use.
  3. Next, you'll need to update the Swashbuckle configuration settings and create a method to read your XML file. Open SwaggerConfig.cs from your App_Start folder and uncomment the following line:

    c.IncludeXmlComments(GetXmlCommentsPath());
  4. Paste the following code as a new method in SwaggerConfig.cs, appending the .BaseDirectory with your XML file path (e.g., @"bin\PetStore.xml") :

    private static string GetXmlCommentsPath()
    {
        return System.AppDomain.CurrentDomain.BaseDirectory + @"[your XML file path]";
    }
Run your API, and navigate to your Swagger UI documentation. Your XML comments should now be displayed for each endpoint.

Next Steps:

For troubleshooting issues and tips on how to integrate additional features, refer to the Swashbuckle README on GitHub.com.

In addition to Swagger UI, SmartBear offers an entire suite of API Delivery and Testing tools. For a complete list of products, visit https://smartbear.com/.