19 November 2026

ASP.NET Core 11 OpenAPI 3.2 for Beginners: Document a Student API

  Asp.Net CS By Example       19 November 2026

When you build an API, other people need to know its URLs, inputs, and responses. OpenAPI is a machine-readable description of those details. ASP.NET Core 11 generates OpenAPI 3.2 documents by default. This small student API shows how to create and inspect one.

How the pieces connect

GET /students/101 → Student response
Endpoint metadata → /openapi/v1.json → API documentation tool

What is OpenAPI 3.2?

OpenAPI is a standard format for describing an HTTP API. Version 3.2 is the version written in the document; it is not your API's URL version. The JSON document can help a person explore endpoints or help tools create client code. It does not add a visual API interface by itself.

Build a student API

Install the .NET 11 SDK. In a terminal, run dotnet new web -n StudentOpenApi -f net11.0, then cd StudentOpenApi and dotnet add package Microsoft.AspNetCore.OpenApi --version 11.0.0. Replace Program.cs with:

var builder = WebApplication.CreateBuilder(args);

// Register the OpenAPI document generator.
builder.Services.AddOpenApi();

var app = builder.Build();

// Keep documentation on for this local learning example.
app.MapOpenApi();

app.MapGet("/students/{id:int}", (int id) =>
    TypedResults.Ok(new Student(id, "Asha", 84)))
   .WithName("GetStudent");

app.Run();

public record Student(int Id, string Name, int Score);

Run dotnet run --urls http://localhost:5055. Open http://localhost:5055/students/101 to see a student response. Then open http://localhost:5055/openapi/v1.json. Near the top, find "openapi": "3.2.0". Search that document for /students/{id} to see how your route is described.

Understand the three important lines

  1. AddOpenApi() registers the generator.
  2. MapOpenApi() exposes the generated document at /openapi/v1.json for the default document name.
  3. MapGet() defines the real endpoint. The document describes it; the document is not the endpoint itself.

What if a tool only understands OpenAPI 3.1?

Some client generators or documentation tools may need an earlier OpenAPI version. Replace builder.Services.AddOpenApi(); with the following configuration. Keep the rest of Program.cs the same:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1;
});

Run the app again and inspect the document's openapi value. Choose the version your consuming tool supports. In a production application, consider whether the document should be publicly available and restrict MapOpenApi() accordingly.

Practice

  1. Add a second endpoint, /students, returning two students. Find it in the generated document.
  2. Rename Student.Score to Mark, rebuild, and see how the response schema changes.
  3. Switch between OpenAPI 3.2 and 3.1, and compare the version field at the top of the JSON.

Continue with the ASP.NET Core student learning path. Read Microsoft's ASP.NET Core 11 release notes and OpenAPI guide for more detail.

logoblog

Thanks for reading ASP.NET Core 11 OpenAPI 3.2 for Beginners: Document a Student API

Previous
« Prev Post

No comments:

Post a Comment

Please do not enter any spam link in the comment box.