Skip to main content

Create Petstore like Swagger UI for ASP.NET Core WEB API

Swagger doesn’t need an introduction as it is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API life-cycle, from design and documentation, to test and deployment. Swagger is an UI representation of your RESTful API. It allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources having none of the implementation logic in place. The Petstore (created by the swagger team) is a demonstration of the beautiful Swagger UI. You can easily integrate the Swagger in your application, but the sad part is you will get a different UI, not same as available @ Petstore. In this post, let’s find out how to create Petstore like Swagger UI for ASP.NET Core WEB API.

Create Petstore like Swagger UI for ASP.NET Core WEB API

In this post, I am not going to show how to integrate Swagger in ASP.NET Core application. If you don’t know, then read this post. By default, you will get Swagger UI shown in the below image.

ASP NET Core Set Swagger UI

To create Petstore like Swagger UI, follow below steps.

  • First, download the swagger-ui package from GitHub and decompress it. You will find a folder named dist. This folder has all the assets for Petstore like UI.
  • Create a wwwroot folder in your ASP.NET Core Web API application, if doesn’t exist. Once created, copy the dist folder and paste it into the wwwroot directory.
  • Next, we need to add middleware to serve static content from the wwwroot folder. To do that, open Startup.cs file and go to Configure method. Add app.UseStaticFiles() to configure static file middleware. Like,
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseStaticFiles();
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.DocumentTitle("My API UI");
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
    

    If you don’t find the method UseStaticFiles(), then include Microsoft.AspNetCore.StaticFiles NuGet package.

  • Run the application and copy the Swagger JSON URL. It would be something like,
    http:///swagger/v1/swagger.json

    On my local machine, the URL is,
    http://localhost:58965/swagger/v1/swagger.json

    We need to configure this URL to get PetStore like UI.

  • Next, open the index.html file located in the dist folder copied in the wwwroot directory. You will find a script block at the end of the file which configures the Swagger UI. The script block has an URL property for Swagger JSON file. Replace the existing URL with the one you copied earlier.

    // Build a system
    const ui = SwaggerUIBundle({
        url: "http://localhost:58965/swagger/v1/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
        ],
        plugins: [
            SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
    })
    
  • The last thing left is to set the application launch URL to index.html. To set it as launch URL, right-click on Project -> select properties -> navigate to debug tab. On debug tab, change Launch Browser value to “dist/index.html”.

    Configure Launch URL for Petstore UI

That’s it. Run the app and you will see the Petstore like UI.

Create Petstore like Swagger UI for ASP.NET Core WEB API

Now, you can easily change the overall design of this UI via tweaking CSS located in the dist folder. It uses swagger-ui.css CSS file for the design. As an example, if you don’t like the light green border around the POST APIs, then you can modify .opblock.opblock-post CSS class and define the border color of your choice. This is handy as it allows to make the UI inline with the application UI theme with very little efforts. The sample source code is available at Github.

Summary

To summarize, the post shows how to create the Petstore like UI in ASP.NET Core Web API application. You can also easily customize the look and feel just via tweaking some CSS classes.

Thank you for reading. Keep visiting this blog and share this in your network. Please put your thoughts and feedback in the comments section.

PS: If you found this content valuable and want to return the favour, then Buy Me A Coffee

5 thoughts to “Create Petstore like Swagger UI for ASP.NET Core WEB API”

  1. I tried your solution, it worked great. But I face issue on Authorize, although I gave the token it is not included in request header. Need some thought where I broke.
    Code I kept in Startup.cs
    c.AddSecurityDefinition(“bearer”, new ApiKeyScheme
    {
    Description = “JWT Authorization header using the Bearer scheme.Example: \\\”Authorization: Bearer {token}\\\”\””,
    Name = “Authorization”,
    In = “header”,
    Type = “apiKey”
    });

      1. With the above UI it is not displaying the Authorize at the top, without this custom UI it is working good. When you observe this customized UI there is Authorize option that will enable only when you add AddSecurityDefinition, but it is not going in the request header.

Leave a Reply

Your email address will not be published. Required fields are marked *