C# Academy · Lesson

Generating OpenAPI Documents

Produce machine-readable API specs.

Lesson 3 of 413 steps

Generating OpenAPI Documents is a free C# Academy lesson on CoddyKit. This is 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, and your progress syncs across the web and the CoddyKit app. The C# Academy course includes 4 lessons in total.

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.

Answer it in the interactive lesson

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.

Free to start

Learn C# with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 93
Lessons: 346

Start learning free View the full course

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. 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. The C# Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 3 of 4.

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