Generating the Document at Build Time

using System.Reflection;

var isGeneratingDocument = Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

var builder = WebApplication.CreateBuilder(args);

if (!isGeneratingDocument)
{
    // Pulls secrets from the vault; the build agent has no credentials for it.
    var secretsFile = builder.Configuration["Secrets:MountedFile"] ?? "/run/secrets/orders.json";
    builder.Configuration.AddJsonFile(secretsFile, optional: false, reloadOnChange: false);
}

builder.Services.AddOpenApi();
builder.Services.AddSingleton<StockReservationWarmer>();

var app = builder.Build();
app.MapOpenApi();

app.MapGet("/inventory/{sku}", (string sku) => TypedResults.Ok(new { sku, onHand = 42 }))
    .WithName("GetStockLevel");

if (!isGeneratingDocument)
{
    await app.Services.GetRequiredService<StockReservationWarmer>().WarmAsync(CancellationToken.None);
}

app.Run();

sealed class StockReservationWarmer(ILogger<StockReservationWarmer> logger)
{
    public async Task WarmAsync(CancellationToken cancellationToken)
    {
        await Task.Delay(50, cancellationToken);
        logger.LogInformation("Reservation cache warmed");
    }
}

name: api-contract
on:
  pull_request:
    # The document also changes when a referenced project (shared DTOs, contracts) does.
    paths:
      - "src/**"

jobs:
  contract:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "10.0.x"
      - name: Build (regenerates openapi/orders-api.json)
        run: dotnet build src/Orders.Api -c Release
      - name: Committed spec matches the code
        run: git diff --exit-code -- src/Orders.Api/openapi/
      - name: No breaking changes against main
        run: |
          mkdir -p /tmp/base
          git show origin/main:src/Orders.Api/openapi/orders-api.json > /tmp/base/orders-api.json
          docker run --rm -v /tmp/base:/base -v "$PWD/src/Orders.Api/openapi:/head" \
            tufin/oasdiff:v1.34.1 breaking /base/orders-api.json /head/orders-api.json --fail-on ERR

using System.Text.Json.Nodes;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

public class OpenApiContractTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task Served_document_matches_committed_contract()
    {
        var cancellationToken = TestContext.Current.CancellationToken;
        using var client = factory.CreateClient();

        var live = await client.GetStringAsync("/openapi/v1.json", cancellationToken);
        var committed = await File.ReadAllTextAsync(
            Path.Combine(AppContext.BaseDirectory, "openapi", "orders-api.json"), cancellationToken);

        Assert.Equal(Normalize(committed), Normalize(live));
    }

    private static string Normalize(string json)
    {
        var document = JsonNode.Parse(json)!.AsObject();
        document.Remove("servers"); // the test host reports http://localhost/
        return document.ToJsonString();
    }
}

public partial class Program;