Add OpenAPI and Scalar documentation #818

Summary

Add OpenAPI documentation and a Scalar UI to this service, using shared API documentation conventions where they work with the service's existing unversioned routes.

This work documents the API as it exists today. It must not introduce API versioning or change endpoint URLs.

Scope

• Configure the service to generate an OpenAPI document containing its public endpoints.
• Expose the Scalar API documentation UI at the standard route, such as /scalar.
• Use shared API documentation defaults when they can be used without enabling API versioning.
• Preserve useful endpoint names, summaries, request and response models, and status-code metadata.
• Replace the existing Swagger UI with Scalar once the OpenAPI document and Scalar UI are working.
• Remove Swagger/Swashbuckle packages and configuration that are no longer needed.

The OpenAPI document's own name or URL, such as /openapi/v1.json, is documentation metadata. It must not add a version segment to API routes or enable API version negotiation.

Preserve Existing Behaviour

Keep the existing API contract and runtime behaviour unchanged, including:

• Endpoint URLs and HTTP methods
• Request models
• Response models
• HTTP status codes
• Validation
• Authentication and authorisation
• Business logic

Do not add /api/v1/... routes or API-version route constraints.

Endpoint Documentation

Provide useful OpenAPI metadata for public endpoints where appropriate:

• Endpoint names
• Summaries and descriptions
• Request models
• Response models
• Expected HTTP status codes

Avoid metadata that only repeats information already clear from the route or model. Keep internal endpoints excluded from the public OpenAPI document where appropriate.

OpenAPI and Scalar

• Generate an OpenAPI document containing all public endpoints exposed by this service.
• Make the document available through the standard OpenAPI route configured for the service.
• Make the Scalar UI available through the standard Scalar route, such as /scalar.
• Ensure Scalar can load the OpenAPI document and inspect the endpoints.
• Do not create separate API documents for API contract versions.

Existing Swagger Configuration

Once OpenAPI generation and Scalar are working:

• Remove Swagger middleware and Swagger UI configuration.
• Remove Swashbuckle package references that are no longer required.
• Preserve useful endpoint metadata when removing the old Swagger setup.

Do not keep two API documentation UIs unless there is a specific requirement to do so.

Tests

Add or update tests to verify:

1. Existing unversioned routes remain accessible.
2. Endpoint behaviour, authorization, request/response contracts, and status codes remain unchanged.
3. The OpenAPI document is available and contains the expected public endpoints.
4. The Scalar UI is available and can load the OpenAPI document.
5. API versioning has not been introduced into route templates or endpoint configuration.

Acceptance Criteria

• OpenAPI generation is configured for the service.
• The OpenAPI document includes the expected public endpoints and their useful contract metadata.
• Scalar is available at the configured standard route and displays the document.
• Existing endpoint URLs and behaviour remain unchanged.
• No API versioning configuration, versioned routes, or version negotiation is added.
• Swagger/Swashbuckle configuration and packages are removed where they are no longer needed.
• Relevant automated tests pass.

Out of Scope

• Introducing API versioning or versioned routes.
• Changing existing request or response contracts.
• Changing authentication, validation, status codes, or business logic.
• Introducing new API functionality.
• Refactoring unrelated application code.