How Do I Generate OpenAPI Documentation in ASP.NET Core 10 Without Swashbuckle?

Introduction

OpenAPI documentation is essential for modern API development. It helps developers understand endpoints, request/response formats, authentication, and how to interact with your API without digging into the code.

For a long time, Swashbuckle has been the most popular library for generating OpenAPI (Swagger) documentation in ASP.NET Core. However, with newer versions like ASP.NET Core 10, Microsoft provides built-in support for OpenAPI generation without needing Swashbuckle.

In this article, we will learn how to generate OpenAPI documentation in ASP.NET Core 10 without Swashbuckle in a simple and practical way.

What is OpenAPI?

OpenAPI is a standard specification for describing REST APIs.

It defines:

• Available endpoints

• HTTP methods (GET, POST, PUT, DELETE)

• Request parameters

• Response formats

• Authentication methods

It is usually represented as a JSON or YAML file.

Why Avoid Swashbuckle?

While Swashbuckle is powerful, there are reasons to avoid it:

• Additional dependency in your project

• Slower startup in some cases

• Less control compared to native implementations

ASP.NET Core 10 provides a cleaner and lightweight alternative using built-in APIs.

Built-in OpenAPI Support in ASP.NET Core 10

ASP.NET Core now includes native OpenAPI support via minimal APIs and built-in services.

You can generate OpenAPI documents using:

• Microsoft.AspNetCore.OpenApi
  n- Endpoint metadata

This approach is lightweight, fast, and fully integrated with the framework.

Step-by-Step Implementation

Step 1: Create a New ASP.NET Core Web API Project

dotnet new webapi -n OpenApiDemo
cd OpenApiDemo

Step 2: Add OpenAPI Package

Install the built-in OpenAPI package:

dotnet add package Microsoft.AspNetCore.OpenApi

Step 3: Configure Services in Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

This registers OpenAPI services in your application.

Step 4: Enable OpenAPI Endpoint

app.MapOpenApi();

This exposes the OpenAPI document, usually at:

/openapi/v1.json

Step 5: Create Sample Endpoint

app.MapGet("/products/{id}", (int id) =>
{
    return new { Id = id, Name = "Sample Product" };
})
.WithName("GetProduct")
.WithOpenApi();

Here:

• WithName() gives the endpoint a unique identifier

• WithOpenApi() includes it in the OpenAPI document

Step 6: Run the Application

dotnet run

Open your browser and visit:

https://localhost:5001/openapi/v1.json

You will see the generated OpenAPI JSON.

Adding More Metadata to OpenAPI

You can enhance your documentation using metadata.

Example: Add Description and Tags

app.MapPost("/products", (Product product) =>
{
    return Results.Created($"/products/{product.Id}", product);
})
.WithName("CreateProduct")
.WithOpenApi(operation =>
{
    operation.Summary = "Create a new product";
    operation.Description = "Adds a product to the system";
    return operation;
});

This improves readability and usability of your API documentation.

Using Typed Results for Better Documentation

Typed results help generate more accurate OpenAPI docs.

app.MapGet("/products", () =>
{
    return Results.Ok(new List<string> { "Item1", "Item2" });
});

This ensures response types are clearly defined in the OpenAPI schema.

Difference Between Built-in OpenAPI and Swashbuckle

Feature	Built-in OpenAPI	Swashbuckle
Dependency	Minimal	External Library
Performance	Faster	Slightly Slower
Setup	Simple	Moderate
UI Support	Not Included	Swagger UI Included
Customization	Code-first	Attribute + Config

How to View OpenAPI Without Swagger UI

Since we are not using Swashbuckle, there is no built-in UI.

You can use:

• Browser (JSON view)

• Postman (import OpenAPI)

• Third-party tools like Redoc

Optional: Add Swagger UI Without Swashbuckle

If you still want UI, you can use external tools like:

• Redoc

• Scalar

These tools can read your OpenAPI JSON and display it nicely.

Best Practices

• Always use WithOpenApi() for endpoints

• Provide clear summaries and descriptions

• Use meaningful route names

• Define response types properly

• Keep your API consistent

Real-World Example

In a production API:

• OpenAPI helps frontend teams integrate faster

• QA teams can test endpoints easily

• Third-party developers can consume APIs without confusion

Conclusion

Generating OpenAPI documentation in ASP.NET Core 10 without Swashbuckle is simple, efficient, and modern. With built-in support, you can reduce dependencies, improve performance, and maintain cleaner code.

By using Microsoft.AspNetCore.OpenApi and minimal APIs, you can create high-quality API documentation with minimal effort.

This approach is ideal for developers who want a lightweight, fast, and scalable solution for API documentation in modern ASP.NET Core applications.