Add Api Versioning #287

Summary

Add API versioning and OpenAPI documentation to this ASP.NET Core Minimal API using the shared Shared.Web library.

The API should initially expose all existing endpoints as V1.

The shared library provides the standard configuration for:

• API versioning using Asp.Versioning
• URL-based API versions
• OpenAPI document generation
• Version-specific OpenAPI documents
• Scalar API documentation

The API should use these shared conventions rather than configuring versioning, OpenAPI or Scalar independently.

Add Shared Library

Add a reference to:

Shared.Web

Do not directly configure Asp.Versioning, OpenAPI or Scalar within this API unless functionality specific to this application requires it.

Configure API Defaults

Register the shared API defaults during application startup.

For example:

builder.Services.AddApiDefaults(options =>
{
    options.Title = "<API Name>";
    options.Description = "<API Description>";
});

Configure the application to expose the standard API documentation:

app.UseApiDefaults();

Replace the title and description with values appropriate for this API.

Version Existing Endpoints

Treat all existing endpoints as API V1.

Existing routes should be updated to use the standard versioned route format:

/api/v1/...

Endpoint route groups should use the version placeholder:

/api/v{version:apiVersion}/...

For example, an existing route:

/api/transactions

should become:

/api/v1/transactions

Use the version constants supplied by TransactionProcessing.ApiDefaults when defining supported versions.

For example:

var api = app.NewVersionedApi("Transactions");

var transactions = api
    .MapGroup("/api/v{version:apiVersion}/transactions")
    .HasApiVersion(ApiVersions.V1);

Map the existing endpoints to V1:

transactions
    .MapGet("/{id:guid}", GetTransaction)
    .MapToApiVersion(ApiVersions.V1);

Apply the same pattern to all existing API endpoints.

Preserve Existing Behaviour

Introducing API versioning must not change the functional behaviour of the existing endpoints.

Existing:

• Request models
• Response models
• HTTP status codes
• Validation
• Authentication/authorisation
• Business logic

should remain unchanged unless a change is specifically required to support versioning.

The purpose of this work is to establish the existing API contract as V1, not redesign the API.

Endpoint Documentation

Ensure endpoints provide useful OpenAPI metadata where appropriate.

For example:

transactions
    .MapGet("/{id:guid}", GetTransaction)
    .MapToApiVersion(ApiVersions.V1)
    .WithName("GetTransaction")
    .WithSummary("Gets a transaction");

Add or retain appropriate metadata for:

• Endpoint names
• Summaries
• Descriptions where useful
• Request models
• Response models
• Expected HTTP status codes

Avoid adding documentation that simply repeats information already obvious from the route or model.

OpenAPI

Verify that the shared library automatically generates the V1 OpenAPI document:

/openapi/v1.json

The document should contain all public V1 endpoints exposed by this API.

The API should not manually register a V1 OpenAPI document.

Future versions such as V2 should be automatically supported by the shared API defaults infrastructure when versioned endpoints are introduced.

Scalar

Verify that the Scalar API documentation UI is available through the standard route:

/scalar

Scalar should expose the V1 OpenAPI definition and allow the API endpoints to be inspected and tested.

Existing Swagger Configuration

If the API currently uses Swashbuckle/Swagger:

• Remove the existing Swagger/Swashbuckle configuration once Scalar and the standard OpenAPI implementation are working.
• Remove Swagger middleware such as UseSwagger() and UseSwaggerUI().
• Remove Swashbuckle package references that are no longer required.
• Preserve any useful API metadata or documentation currently provided through Swagger and migrate it to the new OpenAPI configuration where appropriate.

Do not maintain two separate API documentation implementations unless there is a specific requirement to do so.

Tests

Update existing integration tests to use the V1 routes.

For example:

/api/transactions

becomes:

/api/v1/transactions

Add or update tests to verify:

1. Existing endpoints are accessible through /api/v1/....
2. Existing endpoint behaviour remains unchanged.
3. Requests without a valid API version are rejected where appropriate.
4. Unsupported versions such as /api/v999/... are rejected.
5. /openapi/v1.json is available.
6. The V1 OpenAPI document contains the expected API endpoints.
7. Scalar API documentation is available.

Existing functional tests should continue to pass after their URLs are updated to the V1 routes.

Acceptance Criteria

The work is complete when:

• The API references TransactionProcessing.ApiDefaults.
• AddApiDefaults(...) is registered with an appropriate API title and description.
• UseApiDefaults() is configured.
• All existing public API endpoints are designated as V1.
• Public API routes use the /api/v1/... convention.
• Existing endpoint behaviour remains unchanged.
• /openapi/v1.json is generated and contains the expected endpoints.
• Scalar documentation is available.
• Existing Swagger/Swashbuckle configuration has been removed where applicable.
• Redundant Swagger/Swashbuckle package references have been removed.
• Existing tests have been updated to use the V1 routes.
• Versioning/OpenAPI integration tests have been added or updated.
• All automated tests pass.

Out of Scope

This work should not:

• Introduce V2 endpoints.
• Make breaking changes to existing request or response contracts.
• Refactor application business logic unnecessarily.
• Add application features unrelated to API versioning.
• Duplicate functionality already provided by TransactionProcessing.ApiDefaults.

Future breaking API changes should be implemented as a new API version rather than modifying the established V1 contract.