Testing Swagger and API Documentation

In this lesson, you will learn how to automate the validation of your Swagger/OpenAPI documentation to ensure it never drifts from your actual C# implementation.

The Problem of API Drift

In large-scale systems, it is common for developers to update a controller action—perhaps adding a required query parameter or changing a return type—without updating the underlying Swagger schema. When your documentation serves as the "Source of Truth" for front-end teams or external consumers, this drift leads to broken integrations and wasted debugging time.

Manual verification is brittle. Instead, we treat the OpenAPI specification as a testable artifact within our CI/CD pipeline.

Automating Documentation Verification

To ensure consistency, we treat the generated swagger.json as a testable contract. We can use an integration test that spins up the WebApplicationFactory to retrieve the live generated schema and assert its contents against our expectations.

Here is how you can perform a structural check in a test suite:

[Fact]
public async Task SwaggerDocument_ShouldMatchExpectedContract()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act: Fetch the generated spec
    var response = await client.GetAsync("/swagger/v1/swagger.json");
    var json = await response.Content.ReadAsStringAsync();
    
    // Assert: Use a library like FluentAssertions or JsonDiffPatch
    // to compare against a checked-in "golden file"
    var expectedSchema = await File.ReadAllTextAsync("Contracts/v1-spec.json");
    json.Should().BeEquivalentTo(expectedSchema);
}

Bridging the Gap

By storing a v1-spec.json (or a YAML equivalent) in your repository, you create a "Snapshot Test" for your documentation. If a developer modifies a [ProducesResponseType] attribute or changes an action parameter, the test will fail during the build gate if the generated Swagger doesn't match the snapshot.

This forces developers to consciously decide whether they are making a breaking change to the API contract. If the change is intentional, they update the snapshot file as part of the PR. This ensures that the documentation is never an afterthought, but a first-class citizen of the codebase that evolves in lockstep with your business logic.

Key Takeaway: Automate documentation validation by treating your Swagger output as a testable contract that must be verified against a committed snapshot during your build pipeline.