Exercise - Use Swashbuckle to create an OpenAPI document

Completed

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.

Note

Download the source code to your local computer to complete this exercise. After downloading the file, you will need to unzip it.

Download: ASP.NET Core Web API Application.

  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.

    Visual Studio Solution Opening.

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

    Right-click Manage NuGet Packages.

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

    NuGet Package Manager.

    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.

    File: Startup.cs

  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.

    File Modified: Startup.cs

Generate the OpenAPI document file

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

    Debug in Visual Studio.

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

    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.

    Page Not Found.

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

    Swagger UI Page for OpenAPI.

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

    OpenAPI Document.

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