Set up OpenAPI documentation with Scalar and auth support

[JacobChwastek]

Context

WiSave.Expenses.WebApi currently exposes minimal API endpoints but does not appear to have OpenAPI/Swagger/Scalar configured.

Relevant files:

• src/WiSave.Expenses.WebApi/Program.cs
• src/WiSave.Expenses.WebApi/WiSave.Expenses.WebApi.csproj
• src/WiSave.Expenses.WebApi/Authorization/EndpointExtensions.cs
• src/WiSave.Expenses.WebApi/Authorization/PermissionEndpointFilter.cs
• src/WiSave.Expenses.WebApi/Authorization/Permissions.cs
• src/WiSave.Expenses.WebApi/Endpoints/*

Goal

Add OpenAPI documentation for the expenses API and expose it through Scalar UI, including authentication/authorization support so protected endpoints are documented correctly.

Scope

• Add OpenAPI generation for WiSave.Expenses.WebApi.
• Add Scalar API reference UI.
• Ensure endpoint metadata is useful for API consumers.
• Document auth requirements for endpoints protected by RequirePermission(...).
• Add auth/security scheme support appropriate for the current Portal/BFF header-based flow.
• Make the setup environment-aware so docs are available in development/local environments without exposing unsafe production behavior.
• Review endpoint request/response metadata and add missing Produces, Accepts, summaries, tags, and OpenAPI descriptions where needed.

Current Auth Context

Expenses WebApi authorization is currently based on forwarded user context and permission checks:

• PermissionEndpointFilter returns 403 when user id or required permission is missing.
• RequirePermission(...) adds PermissionMetadata.
• Permissions currently include:
  • expenses:read
  • expenses:write
  • expenses:delete

Acceptance Criteria

• OpenAPI JSON is available for WiSave.Expenses.WebApi.
• Scalar UI is available locally/development.
• Scalar displays all expenses API endpoint groups.
• Protected endpoints clearly show auth/security requirements.
• Permission-protected endpoints document possible 403 responses.
• Endpoint request/response types are discoverable in generated OpenAPI.
• Setup is covered by a smoke/integration test where practical.
• README or developer notes mention how to open Scalar locally.