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.