Controller vs. Minimal: Tailoring Swagger Integration in .NET APIs

In the digital age, the effectiveness of an API is as crucial as its functionality, making clear and comprehensive documentation a necessity. This is where Swagger, a leading tool in API documentation, comes into play, particularly within the .NET. It offers two distinct approaches for API development: the traditional controller-based model and the minimal API model. Each presents unique opportunities for integrating Swagger, a key to unlocking interactive and user-friendly API documentation.

In this blog, we’ll dive into the integration of Swagger in both controller-based and minimal APIs in .NET, exploring their differences, advantages, and challenges. Whether you’re a .NET novice or an expert, this guide will provide valuable insights to enhance your API documentation strategy, ensuring your APIs are not just functional, but also intuitively accessible for developers and users alike.

What is Swagger?

Swagger is a widely used set of tools for implementing the OpenAPI Specification (OAS). It provides a powerful yet user-friendly way to document, design, build, and test APIs. Initially developed as an independent project, Swagger has evolved to become synonymous with API documentation and design.

What is OpenAPI?

The OpenAPI Specification, formerly known as the Swagger Specification, is an API description format for REST APIs. It offers a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to understand the capabilities of a service without accessing its source code.

Are Swagger and OpenAPI the Same?

While Swagger and OpenAPI are often used interchangeably, they are not exactly the same. Swagger refers to the suite of tools around the OpenAPI Specification, whereas OpenAPI is the specification itself. In simpler terms, OpenAPI defines the standard, and Swagger provides the tools to implement that standard.

Key Features

• API Documentation: Swagger automatically generates interactive API documentation that makes it easy for developers to understand and try out the API.
• Code Generation: It supports code generation in multiple languages, allowing developers to quickly create client and server code from an OpenAPI specification.
• Interactive API Testing: Swagger UI facilitates easy testing of API endpoints directly from the browser, improving the testing workflow.
• Design & Mocking: It offers tools for API design and the ability to create mock implementations, speeding up the development process.

Impact on API Development

Swagger revolutionizes API development by making it more accessible, efficient, and collaborative. It’s particularly beneficial in environments where clear communication and integration of different software components are essential. In the next sections, we’ll delve into how Swagger integrates into the diverse world of .NET APIs, showcasing its adaptability and importance in modern software development.

Differentiating Between Controller-Based and Minimal APIs

In .NET, APIs can be developed using two distinct approaches: the controller-based model and the minimal API model. Understanding the differences between these two is crucial for selecting the right approach for your project.

Controller-Based APIs

Controller-based APIs in .NET implement the controller part of the traditional MVC (Model-View-Controller) pattern. They provide a structured approach to API development, where each controller class handles requests for a specific route or resource.

[ApiController]
[Route("[controller]")]
public class CarController : ControllerBase
{
    [HttpGet]
    public ActionResult<List<Car>> GetAll()
    {
      // Implementation to return car data
    }
}

Minimal APIs

Introduced in .NET 6, minimal APIs are a leaner way to create web APIs with fewer files and less boilerplate code. They are ideal for microservices and small-scale applications.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("MinimalApi/Car", () => {
    // Implementation to return car data
});

app.Run();

Key Differences

1. Structure: Controller-based APIs use a class-based structure, whereas minimal APIs are more route-focused with a functional style.
2. Boilerplate Code: Controller-based APIs require more boilerplate, including class and method decorations. Minimal APIs are succinct, reducing boilerplate.
3. Flexibility vs. Simplicity: Controller-based APIs offer more flexibility and features out of the box. Minimal APIs opt for simplicity and a more straightforward approach.

Pros and Cons

Setting Up Swagger in Controller-Based APIs

Swagger is an essential tool for documenting and testing APIs. Integrating Swagger with controller-based APIs in .NET enhances the development experience by providing a user-friendly interface for interacting with your API. Here’s how you can set it up:

Step 1: Install Swagger Dependencies

First, add the necessary Swagger dependencies to your project. You can do this via the NuGet Package Manager or by adding them directly to your project file.

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.5" />
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
</ItemGroup>

In addition, when starting a new project in Visual Studio, you have the option to automatically enable Swagger support. During the project setup, simply check the box that says “Enable OpenAPI support” or similar (the exact wording may vary depending on the version of Visual Studio). This convenience feature streamlines the setup process by automatically including the necessary Swagger dependencies and configuration in your new project.

Step 2: Configure Swagger in Program.cs

In your Program.cs, add Swagger generation services.

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
  options.SwaggerDoc("v1", new OpenApiInfo
  {
    Version = "v1",
    Title = "OpenApi Demo - Controller",
    Description = "A web api showcasing how to create a good open api specification in controller-based project.",
    TermsOfService = new Uri("https://indigo.si"),
    Contact = new OpenApiContact
    {
      Name = "Luka Zlatecan",
      Url = new Uri("https://indigo.si/contact/")
    },
  });

  // Just for executing project
  //var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
  //options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));

  //For all projects. Can be a problem if other .xml files are present
  List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList();
  xmlFiles.ForEach(xmlFile => options.IncludeXmlComments(xmlFile));
});

In a single project setup, integrating XML comments into Swagger UI helps clarify API descriptions. For apps with several projects, this integration takes comments from all XML files in the main folder, providing a full API overview in Swagger.

Also, remember to include the GenerateDocumentationFile XML tag in your .csproj file. This tag enables the generation of an XML file with your code’s comments, crucial for Swagger’s documentation.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

By doing this, your Swagger documentation becomes more comprehensive, enhancing the overall usability of your API. After setting up your application builder and adding services, you will enable the Swagger middleware.

app.UseSwagger();
app.UseSwaggerUI();

/// <summary>
/// Get all cars.
/// </summary>
/// <remarks>All cars are good.</remarks>
/// <returns>A list of Cars.</returns>
/// <response code="200">All cars.</response>
[HttpGet(Name = "GetAllCars")]
[ProducesResponseType(typeof(List<Car>), StatusCodes.Status200OK)]
public ActionResult<List<Car>> GetAll()
{
    return Ok(_carRepository.GetAll());
}

Setting Up Swagger in Minimal APIs

While the initial steps to set up Swagger in minimal APIs are similar to those in controller-based APIs, the key difference lies in how the endpoints are defined and configured. In minimal APIs, there are several methods to annotate and document your endpoints for Swagger. It’s also important to note that if you are starting your project with Visual Studio, you should uncheck “Use controllers” checkbox in order to use minimal APIs.

Step 1: Add Swagger Dependencies

This step mirrors what was done in the controller-based setup, requiring the addition of Swagger-related packages to your project.

Step 2: Configure Swagger Services

Similar to the process in the controller-based setup, you add and configure Swagger services in Program.cs in the same way.

app.MapGet("MinimalApiFluent/Car", GetAll)
   .WithName("MinimalFluentGetAllCars")
   .WithSummary("Get all cars.")
   .WithDescription("All cars are good.")
   .Produces<List<Car>>()
   .WithOpenApi();

group.MapGet("/", GetAll)
   .WithOpenApi(operation =>
   {
       operation.OperationId = "MinimalOperationGetAllCars";
       operation.Summary = "Get all cars.";
       operation.Description = "All cars are good.";
       return operation;
   });

app.MapGet("MinimalApiXml/Car", GetAll);
/// <summary>
/// Get all cars.
/// </summary>
/// <remarks>All cars are good.</remarks>
/// <returns>A list of Cars.</returns>
/// <response code="200">All cars.</response>
private Ok<List<Car>> GetAll()
{
    return TypedResults.Ok(_carRepository.GetAll());
}

Conclusion

In the realm of .NET, the integration of Swagger presents a versatile and adaptable solution, catering to diverse project needs and preferences. The choice of approach for incorporating Swagger should be in harmony with your application’s scale and intricacy:

• Controller-Based API Integration: This method shines in larger-scale applications where a structured design and comprehensive documentation are of paramount importance. It excels in scenarios involving complex routing and controllers, offering a rich suite of documentation features that greatly benefit such environments.
• Minimal API Integration: On the other hand, this approach is more suitable for smaller projects where simplicity and rapid setup are the main objectives. Whether employing standard methods or XML comments, minimal APIs provide an efficient and streamlined avenue for integrating Swagger. This makes them particularly apt for projects that are less complex or those requiring swift development cycles.

Irrespective of the selected strategy, the crux lies in striking a balance between the specific demands of your project and the inherent strengths of each approach. This balance ensures that the integration of Swagger not only complements but also enhances the overall development experience and the effectiveness of the resulting API documentation.

Practical Example on GitHub

To provide a clearer understanding and practical insights, I have created a simple project that demonstrates the integration of Swagger in both controller-based and minimal APIs in .NET. This example covers the various methods discussed and serves as a great starting point for your own implementations. You can find this project on GitHub at https://github.com/indigolabsslo/IndigoLabs.OpenApi. Explore and experiment with it to see how Swagger integration works in different scenarios.

Additional Resources

For more detailed information and best practices on integrating Swagger in .NET applications, you can visit the official Microsoft documentation at https://aka.ms/aspnetcore/swashbuckle. This resource provides in-depth guidance, helping you to further refine and optimize your Swagger integration.