Post
Ask Question

Swagger API Filtering in ASP.NET Core

Introduction

Swagger is a powerful tool for documenting and testing APIs in ASP.NET Core applications. It generates interactive API documentation, making it easier for developers to understand and work with your APIs. However, in some cases, you may want to expose only specific APIs to Swagger documentation while hiding others. This can be useful when you have internal or administrative APIs that should not be visible to external users. In this article, we will explore how to selectively show only specific APIs on Swagger in ASP.NET Core with practical examples.

Prerequisites

Before we get started, make sure you have the following prerequisites.

  1. Visual Studio or Visual Studio Code
  2. ASP.NET Core SDK
  3. Swashbuckle.AspNetCore NuGet package (Swagger for ASP.NET Core)

Step 1. Create an ASP.NET Core Web API Project

If you don't already have an ASP.NET Core Web API project, you can create one using the following command.

dotnet new webapi -n MyApi

Step 2. Install Swashbuckle.AspNetCore

To enable Swagger documentation in your ASP.NET Core project, you need to install the Swashbuckle.AspNetCore NuGet package. You can do this using the Package Manager Console or by running the following command.

dotnet add package Swashbuckle.AspNetCore

Step 3. Configure Swagger

Next, open the Startup.cs file in your project and add the following code to the ConfigureServices and Configure methods.

// ConfigureServices method
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

// Configure method
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

This code configures Swagger with a default documentation endpoint.

Step 4. Show Only Specific APIs on Swagger

To selectively show only specific APIs on Swagger, you can use the [ApiExplorerSettings] attribute on your controller methods. Here's an example.

[ApiExplorerSettings(IgnoreApi = true)] // This API will be hidden from Swagger
[HttpGet("hidden")]
public IActionResult HiddenApi()
{
    return Ok("This API is hidden from Swagger.");
}

[HttpGet("visible")]
public IActionResult VisibleApi()
{
    return Ok("This API is visible on Swagger.");
}

In this example, the HiddenApi method is decorated with [ApiExplorerSettings(IgnoreApi = true)], which tells Swagger to ignore this API during documentation generation. The VisibleApi method, on the other hand, is not decorated, so it will be visible on Swagger.

Step 5. Run Your ASP.NET Core Application

Now that you've configured Swagger and marked specific APIs as hidden or visible, you can run your ASP.NET Core application using the following command:

dotnet run

Your application will start, and you can access Swagger documentation by navigating to https://localhost:5001/swagger (or the respective URL for your project).

Conclusion

In this article, we've learned how to selectively show only specific APIs on Swagger in an ASP.NET Core application. By using the [ApiExplorerSettings] attribute to mark certain APIs as hidden or visible, you can control which endpoints are documented and exposed via Swagger. This can be particularly useful when you want to keep administrative or internal APIs hidden from external users while providing comprehensive documentation for the APIs that should be accessible to everyone.


Similar Articles