Generate and Diff OpenAPI Specs in .NET

Goal: Generate OpenAPI specification files from .NET APIs and detect breaking changes between versions.

Setup

Install Swashbuckle tools:

dotnet add package Swashbuckle.AspNetCore.Swagger
dotnet tool install --global Swashbuckle.AspNetCore.Cli
dotnet build

Generate OpenAPI Spec

dotnet build
swagger tofile --output "openapi.json" bin/Debug/net8.0/bkr-provider-api.dll v1

Replace bkr-provider-api.dll with your assembly name and v1 with your API version.

Compare Specs

Use openapi-diff to detect breaking changes:

## Compare two local files
docker run --rm -v ${PWD}:/spec openapitools/openapi-diff /spec/openapi_v4.json /spec/openapi_v5.json

## Compare local file with running API
docker run --rm -v ${PWD}:/spec openapitools/openapi-diff /spec/openapi_v4.json http://host.docker.internal:5062/swagger/v5/swagger.json

host.docker.internal points to the host machine’s localhost.