Openapi

var builder = WebApplication.CreateBuilder(args);builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment()){    app.MapOpenApi();  // Serves at /openapi/v1.json}

group.MapPost("/", CreateOrder)    .WithName("CreateOrder")    .WithSummary("Create a new order")    .WithDescription("Creates a new order for the specified customer.")    .Produces<OrderResponse>(StatusCodes.Status201Created)    .ProducesValidationProblem()    .ProducesProblem(StatusCodes.Status500InternalServerError);

static async Task<Results<Created<OrderResponse>, ValidationProblem>> CreateOrder(    CreateOrderRequest request, ISender sender, CancellationToken ct){    var result = await sender.Send(new CreateOrder.Command(request), ct);    return result.IsSuccess        ? TypedResults.Created($"/api/orders/{result.Value.Id}", result.Value)        : TypedResults.ValidationProblem(result.Errors);}

builder.Services.AddOpenApi(options =>{    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();});
internal sealed class BearerSecuritySchemeTransformer(    IAuthenticationSchemeProvider authSchemeProvider) : IOpenApiDocumentTransformer{    public async Task TransformAsync(OpenApiDocument document,        OpenApiDocumentTransformerContext context, CancellationToken ct)    {        var schemes = await authSchemeProvider.GetAllSchemesAsync();        if (!schemes.Any(s => s.Name == "Bearer"))            return;
        document.Components ??= new OpenApiComponents();        document.Components.SecuritySchemes = new Dictionary<string, IOpenApiSecurityScheme>        {            ["Bearer"] = new OpenApiSecurityScheme            {                Type = SecuritySchemeType.Http,                Scheme = "bearer",                BearerFormat = "JWT",                In = ParameterLocation.Header            }        };
        foreach (var operation in document.Paths.Values.SelectMany(p => p.Operations))        {            operation.Value.Security ??= [];            operation.Value.Security.Add(new OpenApiSecurityRequirement            {                [new OpenApiSecuritySchemeReference("Bearer", document)] = []            });        }    }}

builder.Services.AddOpenApi(options =>{    options.AddDocumentTransformer((document, context, ct) =>    {        document.Info = new()        {            Title = "Checkout API",            Version = "v1",            Description = "API for processing orders and payments."        };        return Task.CompletedTask;    });});

builder.Services.AddOpenApi("v1");builder.Services.AddOpenApi("internal", options =>{    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();});
// Endpoints choose their document via WithGroupNameapp.MapGet("/public", () => "Hello").WithGroupName("v1");app.MapGet("/admin", () => "Secret").WithGroupName("internal");

/// <summary>Retrieves a project board by ID.</summary>/// <param name="id">The project board ID.</param>/// <response code="200">Returns the project board.</response>/// <response code="404">Board not found.</response>static async Task<Results<Ok<Board>, NotFound>> GetBoard(int id, AppDbContext db){    var board = await db.Boards.FindAsync(id);    return board is not null ? TypedResults.Ok(board) : TypedResults.NotFound();}

options.AddSchemaTransformer((schema, context, ct) =>{    if (context.JsonTypeInfo.Type == typeof(decimal))    {        schema.Format = "decimal";    }    return Task.CompletedTask;});

app.MapGet("/old", () => "deprecated")    .AddOpenApiOperationTransformer((operation, context, ct) =>    {        operation.Deprecated = true;        return Task.CompletedTask;    });

app.MapOpenApi("/openapi/{documentName}.yaml");

// BAD — removed from .NET 9+ templates, maintenance concernsbuilder.Services.AddSwaggerGen();app.UseSwagger();app.UseSwaggerUI();
// GOOD — built-in OpenAPIbuilder.Services.AddOpenApi();app.MapOpenApi();

// BAD — deprecated, produces ASPDEPR002 warningapp.MapGet("/", () => "hello").WithOpenApi(op => { op.Deprecated = true; return op; });
// GOOD — use per-endpoint operation transformerapp.MapGet("/", () => "hello")    .AddOpenApiOperationTransformer((op, ctx, ct) =>    {        op.Deprecated = true;        return Task.CompletedTask;    });

// BAD — Results.Ok doesn't contribute to OpenAPI schemastatic async Task<IResult> GetOrder(Guid id, AppDbContext db){    var order = await db.Orders.FindAsync(id);    return order is not null ? Results.Ok(order) : Results.NotFound();}
// GOOD — TypedResults with union return typestatic async Task<Results<Ok<Order>, NotFound>> GetOrder(Guid id, AppDbContext db){    var order = await db.Orders.FindAsync(id);    return order is not null ? TypedResults.Ok(order) : TypedResults.NotFound();}

// BAD — client generators produce poor method names without operationIdgroup.MapGet("/{id:guid}", GetOrder);
// GOOD — operationId feeds into generated client method namesgroup.MapGet("/{id:guid}", GetOrder).WithName("GetOrder");

// BAD — OpenApiAny types removed in Microsoft.OpenApi v2.xschema.Example = new OpenApiString("2025-01-01");
// GOOD — use JsonNode from System.Text.Json.Nodesschema.Example = JsonValue.Create("2025-01-01");