C Sharp - Annotation - OpenAPI - ApiExplorerSettings

[ApiExplorerSettings(GroupName = “02-Tyler”)]

From Open AI on 3/27/2025

The [ApiExplorerSettings(GroupName = “02-Tyler”)] attribute in .NET is used for customizing the way API documentation is displayed, particularly when generating Swagger or OpenAPI documentation. It is part of the Microsoft.AspNetCore.Mvc.ApiExplorer namespace.
Purpose of [ApiExplorerSettings(GroupName = “02-Tyler”)]:
1. API Grouping:
* The GroupName property helps categorize or group your API controllers into specific sections within the Swagger UI or any other documentation generated by API Explorer.
* By assigning a group name (like “02-Tyler”) to a controller, it can be visually separated from other API controllers in the generated Swagger UI, making it easier for users to navigate large APIs by categorizing related endpoints together.
2. Filtering API Documentation:
* This attribute can be particularly useful in scenarios where you want to generate multiple sets of API documentation (for example, versioned APIs or APIs with distinct functionality) within the same application. By grouping controllers into different API groups, you can filter which controllers should be included under which section in the documentation.
* For example, if you have versioned APIs, you can group them by version (e.g., “v1”, “v2”, etc.), and this grouping will be reflected in the Swagger UI.

Example:

Suppose you have multiple controllers in your API, and you want to group them into a section named “02-Tyler” in the Swagger documentation.

[ApiExplorerSettings(GroupName = "02-Tyler")]
[ApiController]
[Route("api/[controller]")]
public class TylerController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("Tyler API");
    }
}

In this example:

• The TylerController will be placed under the “02-Tyler” section in Swagger UI or other API documentation.
• This allows you to segregate your APIs into logical groupings based on your needs.

Benefits:

• Better Organization: If you have a large API with different modules, you can organize your controllers by different groups, making the API easier to navigate for consumers.
• Improved Documentation: Helps consumers of the API see related controllers or functionality grouped under specific names.
• Support for Multiple API Versions: This is especially useful when maintaining multiple versions of an API. For example, you can group all version 2 endpoints under “v2” and version 1 under “v1”, etc.

Example for Multiple Groups:
If you have multiple controllers and want to group them into different categories, you can do this like so:

// Group for API version 1
[ApiExplorerSettings(GroupName = "v1")]
[ApiController]
[Route("api/[controller]")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("Version 1 of Products");
    }
}

// Group for API version 2
[ApiExplorerSettings(GroupName = "v2")]
[ApiController]
[Route("api/[controller]")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("Version 2 of Products");
    }
}

In this case:

• The ProductsV1Controller will be grouped under “v1”.
• The ProductsV2Controller will be grouped under “v2”.
• When viewing the Swagger UI, the user will be able to toggle between the two groups to see the different versions of the API.

Summary:
The [ApiExplorerSettings(GroupName = “02-Tyler”)] attribute allows you to categorize or group your API controllers under a custom name in the Swagger UI or any other documentation, making it easier to organize and manage large or versioned APIs. It is especially useful for API organization and documentation clarity.

How would you organize the initialization portion in program.cs to make this work?

To organize the initialization portion in Program.cs and ensure that the [ApiExplorerSettings(GroupName = “02-Tyler”)] works properly, you need to set up your API documentation generation (Swagger/OpenAPI) correctly using Swashbuckle or another OpenAPI generator library.

Here’s an example of how to configure your Program.cs file to ensure that API grouping works correctly with Swashbuckle and the ApiExplorerSettings attribute:
Steps:
1. Install the Necessary NuGet Packages: First, make sure you have the required NuGet packages installed:
* dotnet add package Swashbuckle.AspNetCore
This will add Swashbuckle for Swagger generation.
3. Modify Program.cs to Set Up Swagger and API Groups: In your Program.cs, you need to:
* Add Swagger services.
* Configure Swagger to generate documentation with grouping based on the GroupName you set via the [ApiExplorerSettings(GroupName = “02-Tyler”)] attribute.

• Enable middleware to serve the Swagger UI.

Here’s how you can organize the Program.cs for this:
Example Program.cs:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();

// Add Swagger services
builder.Services.AddSwaggerGen(options =>
{
    // You can optionally add custom configuration here.
    // This configures the Swagger to use groupings based on the ApiExplorer settings.

    // Example: If you want to specify custom metadata (optional)
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    options.SwaggerDoc("02-Tyler", new OpenApiInfo { Title = "Tyler API", Version = "v1" });

    // Optionally, you can add a filter to group by ApiExplorer settings if you have complex scenarios.
    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        var groupName = apiDesc.GroupName;
        return groupName == null || groupName.Equals(docName, StringComparison.OrdinalIgnoreCase);
    });
});

var app = builder.Build();

// Use Swagger middleware
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();

    // Serve Swagger UI, specify the endpoint to Swagger JSON documentation.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.SwaggerEndpoint("/swagger/02-Tyler/swagger.json", "Tyler API");
        c.RoutePrefix = string.Empty;  // To access Swagger UI at the root URL
    });
}

// Use routing and controllers
app.UseRouting();
app.MapControllers();

app.Run();

Explanation:
1. AddSwaggerGen:
* This configures Swagger services and specifies which documentation to generate.
* In this case, we define two Swagger docs: one for the default “v1” API and another for the “02-Tyler” group. These will be listed in the Swagger UI.
2. DocInclusionPredicate:
* This predicate ensures that only the controllers that belong to a specific group (based on the GroupName property in [ApiExplorerSettings]) are included in the corresponding Swagger group. It checks the GroupName from the ApiExplorerSettings attribute in the controllers and matches it to the Swagger doc name.
3. UseSwaggerUI:
* Configures Swagger UI to show multiple groups of documentation. You specify different Swagger JSON endpoints for each group (in this case, the “02-Tyler” API group is separate from the default “v1” group).
4. Route Prefix:
* The RoutePrefix = string.Empty; line configures Swagger UI to be available at the root of your application (/), but this is optional.

Example Controllers:

// Group for "02-Tyler"
[ApiExplorerSettings(GroupName = "02-Tyler")]
[ApiController]
[Route("api/[controller]")]
public class TylerController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("Tyler API");
    }
}

// Default group (v1)
[ApiExplorerSettings(GroupName = "v1")]
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("Product API V1");
    }
}

Final Steps:
* When you launch your application, Swagger will generate two different sets of API documentation:
* You can view these sections in the Swagger UI, which will display them as separate API groups.
* One for the v1 API (products, for example).
* One for the “02-Tyler” API (Tyler-related endpoints).

Swagger UI Access:
1. When running the application, navigate to http://localhost:/swagger/ to access the Swagger UI.
2. You should see two different API groups:
* My API V1 (for your default versioned APIs like ProductsController).
* Tyler API (for your “02-Tyler” API group like TylerController).

This setup makes it easy to organize and document different sections of your API using Swashbuckle and ApiExplorerSettings.