Server URL is hardcoded to https://api.alteg.io/api/v1, causing V2 paths like /api/v2/companies/{id}/tags to resolve incorrectly as /api/v1/api/v2/....
Change base URL to https://api.alteg.io/api and use explicit version prefixes in all paths.
# Before
servers:
- url: 'https://api.alteg.io/api/v1'
# After
servers:
- url: 'https://api.alteg.io/api'Add /v1 prefix to all existing paths:
# Before
'/companies':
'/auth':
'/company/{location_id}':
# After
'/v1/companies':
'/v1/auth':
'/v1/company/{location_id}':Remove /api prefix:
# Before
'/api/v2/companies/{location_id}/activities':
'/api/v2/companies/{company_id}/tags':
# After
'/v2/companies/{location_id}/activities':
'/v2/companies/{company_id}/tags':Add versioning section to info.description:
# API Versioning
The API uses URL path versioning. Currently available versions:
- **V1** (`/v1/...`) - Stable, full-featured API
- **V2** (`/v2/...`) - New endpoints with improved design
Both versions are production-ready. New features may be released
in V2 only. V1 endpoints are maintained for backward compatibility.
Base URL: `https://api.alteg.io/api`
Example requests:
- V1: `GET https://api.alteg.io/api/v1/companies`
- V2: `GET https://api.alteg.io/api/v2/companies/{id}/tags`Update URL mentions in info.description:
https://api.alteg.io/api/v1→https://api.alteg.io/api
- Files in
paths/directory (connected via$ref) - Schemas, responses, components
- operationId values
- Arazzo test files (they reference operationId, not URLs)
make lint # OpenAPI validation
make test-api # Arazzo fast-check
make build-dev # Build documentation| Risk | Mitigation |
|---|---|
| Break existing spec references | Lint check after changes |
| Arazzo tests fail to find operationId | operationId unchanged |
| External systems use spec directly | Breaking change, internal docs only |