Exercise - Use Swashbuckle to create an OpenAPI document

• 8 minutes

In this exercise, you're going to add Swagger and Swagger UI to an ASP.NET Core web API application. The Swagger tooling assists you in creating the OpenAPI document that describes your web API.

1. Select the Download raw file button.
2. Unzip the exercise.zip file.

Add the Swagger tooling

1. Open Visual Studio and find the ASP.NET Core Web API app.

   

2. In Solution Explorer, right-click the project and select the Manage NuGet Packages menu.

   

3. In NuGet Package Manager, search Swashbuckle.AspNetCore. Select the package and install it.

   

   The NuGet package has now been installed. Close the NuGet Package Manager tab.

Configure Swashbuckle to generate an OpenAPI document

1. Open the Startup.cs file.

   

2. Add the following directive just above the line, namespace InventoryManagement.ApiApp.

   /* === using directive BEGIN === */
   using Microsoft.OpenApi.Models;
   /* === using directive END === */
   

3. Replace all of the code inside of the ConfigureServices(IServiceCollection) method with the following code:

       services.AddControllers();
   
       /* === SwaggerGen BEGIN === */
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
       });
       /* === SwaggerGen END === */
   

4. Within the Configure(IApplicationBuilder, IWebHostEnvironment) method, find the if (env.IsDevelopment()) conditional statement and replace everything above that statement with the following code:

       /* === SwaggerUI BEGIN === */
       app.UseSwagger(c =>
       {
           c.PreSerializeFilters.Add((swagger, httpReq) => {
               var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
               swagger.Servers = new List<OpenApiServer>() { server };
           });
       });
       app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
       /* === SwaggerUI END === */
   

   Note

   It's very important that Swagger endpoints are only enabled in the development environment. Otherwise, it could expose your API to the public.

   You've now completed activating the OpenAPI document feature to your ASP.NET Core Web API app. Save the Startup.cs file. Your changes might look like the following screenshot.

   

Generate the OpenAPI document file

1. Select the debug button at the top-middle of Visual Studio.

   

   It automatically opens your web browser and shows the Swagger UI page.

   

   You may see the 404 error page. In this case, enter the URL, https://localhost:<port_number>/swagger, to your browser's address bar. In the following screenshot, the URL is https://localhost:44371/swagger, for example.

   

2. Select the link to open the OpenAPI document page.

   

3. The OpenAPI document is rendered on-the-fly.

   

Your ASP.NET Core Web API app is now ready to produce the OpenAPI document.