C# Academy · Lesson

Generating OpenAPI Documents

Produce machine-readable API specs.

Generating OpenAPI Documents is a free C# Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the C# Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is OpenAPI?

OpenAPI is a standard, machine-readable description of an HTTP API. From it you can generate docs, client SDKs and test tooling.

.NET 9 ships built-in OpenAPI document generation, replacing the older Swashbuckle dependency for many apps.

// OpenAPI document = JSON describing paths, schemas, params

The Microsoft.AspNetCore.OpenApi Package

The built-in support lives in Microsoft.AspNetCore.OpenApi. In .NET 9 templates it is already referenced.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi exposes the generated document at an endpoint. By default it serves at /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Restricting to Development

It is common to expose the document only in development to avoid leaking your surface area in production.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

Describing Endpoints

OpenAPI metadata is enriched from your code. Use WithSummary, WithDescription and WithTags on minimal API endpoints.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Documenting Responses

Declare the response types and status codes so the document lists them accurately.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Document Transformers

Customize the whole document - title, version, servers - with a document transformer passed to AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Operation Transformers

An operation transformer tweaks individual operations - for example, adding a common header parameter to every endpoint.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Adding a UI

The built-in generator produces the JSON document but no UI. Pair it with a viewer like Scalar or Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Generating at Build Time

You can emit the OpenAPI file during the build (no running server) using the Microsoft.Extensions.ApiDescription.Server tooling, handy for CI client generation.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Quick Check

Confirm the .NET 9 OpenAPI basics.

Recap

You generated OpenAPI documents:

AddOpenApi() registers the generator; MapOpenApi() serves the JSON.
Enrich endpoints with WithSummary, Produces and tags.
Document and operation transformers customize the output.
Pair with Scalar or Swagger UI for an interactive view.

Next: documenting versioned APIs.

Frequently asked questions

Is the “Generating OpenAPI Documents” lesson free?

Yes — the full text of “Generating OpenAPI Documents” is free to read here on the web, and the C# Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the C# Academy course, upgrade to CoddyKit PRO.

What will I learn in “Generating OpenAPI Documents”?

Produce machine-readable API specs. You practise C# Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start C# Academy?

No prior experience is required. C# Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Generating OpenAPI Documents” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this C# Academy lesson?

Yes. Every C# Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to C# Academy