Post
Ask Question

Open API Documentation and Swagger alternatives in .NET 9

Introduction

The Microsoft.AspNetCore.OpenApi package offers built-in support for generating OpenAPI documents in ASP.NET Core applications. It provides several key features to enhance API documentation. First, it enables the generation of OpenAPI documents at runtime, allowing developers to access them through a dedicated application endpoint. Additionally, it includes "transformer" APIs, which provide flexibility to modify the generated documentation as needed. Furthermore, the package supports the creation of multiple OpenAPI documents from a single application, making it easier to manage and organize API specifications efficiently. 

Agenda

In this article, we will understand the following concepts in detail.

  • Simple .Net Core Web API Project
  • Understanding about Open API dcoumentation
  • Swagger UI inclusion
  • ReDoc Open API
  • Scalar Open API

Simple .NET Core Web API Project

We will create a simple .Net core Web API project with the following steps in Visual Studio 2022.

  1. Open Visual Studio 2022, Click on "Create new Project" then select the "ASP.NET Core Web API" option and click on "Next". 
    Visual studion
  2. Enter the project named "OpenAPIDocDemo" in the preferred location like below and click on "Next".
    OpenAPI
  3. The Additional Information window is shown below. for this simple demo, we are keeping the info as-is and then clicking on the "Create" button.
    Create
  4. After clicking on the "Create" button it shows the project like below.
    Project
  5. We are done with a simple .Net Core Web API project.

Understanding about OpenAPI documentation

In the created project, we can observe the following referenced package "Microsoft.AspNetCore.OpenApi" provides built-in support of OpenAPI documentation.

OpenAPI documentation'

The Program.cs file has the following highlighted information about OpenAPI support.

OpenAPI support

Let's run the project and append the following "openapi/v1.json" in the browser localhost URL (Ex: localhost:7158/openapi/v1.json). We can observe the following screen.

Localhost

It indicates without doing even a small line of code changes, The.NET9 Web API supports/generates JSON documents with the standard format of API documentation.

Swagger UI Inclusion

Let's make very minimal changes in this demo project to include Swagger UI (our very owned habituated API documentation.

  • Install the following package, "Swashbuckle.AspNetCore.SwaggerUI" from Nuget.
    AspNetCore
  • Add the following lines of code to the Program.cs file below to the existing code line "app.MapOpenApi();" 
    app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "v1");
});

That's it. We are done with Swagger UI inclusion in our .NET API project. Let's run the project again with the sample URL (https://localhost:7158/swagger/index.html). We can see the following page.

.NET API project

ReDoc UI Open API Document

Let's try to include ‘ReDoc” API documentation as well in our project.

  • Install the following Nuget package “Swashbuckle.AspNetCore.ReDoc”
    Nuget package
  • Add the following lines of code to the Program.cs file. 
    app.UseReDoc(options =>
{
    options.SpecUrl("/openapi/v1.json");
});

It's that simple..!!. We just included ReDoc API documentation in our .NET API project. Let's run the project again with the sample URL (https://localhost:7158/api-docs/index.html). We can see the following page.

ReDoc API

Scalar UI Open API Document

Let's include ‘Scalar UI” Open API documentation in our project as well.

  • Add the following Nuget package “Scalar.AspNetCore” to our project.
    Scalar UI
  • Add the following simple line of code to our Program.cs file. 
    app.MapScalarApiReference();
  • So, After the inclusion of all aforesaid Open API document-related code inclusions in the Program.cs file, the code looks like below. 
    using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container
builder.Services.AddControllers();
builder.Services.AddOpenApi(); // Learn more at https://aka.ms/aspnet/openapi
var app = builder.Build();
// Configure the HTTP request pipeline
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });
}
app.UseReDoc(options =>
{
    options.SpecUrl("/openapi/v1.json");
});

app.MapScalarApiReference();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Let's run our project with the sample URL (https://localhost:7158/scalar/), and the screen looks like the one below.

Project

The Scalar API provides more GUI-friendly features with the support of multiple programming languages of sample code if needed. These are really helpful whenever other development teams try to include/call our API in an easy way.

Let's try for a sample C# code for one of our existing Get methods in this sample project in the following way.

Get method

References

The Source Code of this aforesaid project is included in this article as well for reference (OpenAPIDocDemo.zip).

Summary

In this article, we explored Simple .NET Core Web API with details about Open API documentation and other API documentation UI integrations of Swagger UI, ReDco, and Scalar. These are really helpful for our day-to-day projects in APIs for testing or providing the API documentation of other development teams.​​​​​​


Similar Articles