Swagger

Quick reference for consulting and exploring the backend HTTP APIs.

Swagger UI Relative Link

• Swagger UI: /swagger
• OpenAPI JSON: /swagger/v1/swagger.json

Availability by Environment

• Swagger UI and the OpenAPI JSON are active only with ASPNETCORE_ENVIRONMENT=Development: local development (dotnet run / dotnet watch with the launchSettings.json profile) or the source package started in debug.
• In Production (IIS and Linux installations, demo) Swagger is turned off for security: /swagger/, /swagger/index.html and /swagger/v1/swagger.json return 404, even to an authenticated administrator. The schema would list the entire API surface, including administrative actions (e.g. /api/Meta/Restart, ReloadLicenseFromAppsettings).
• To explore the APIs, use a Development environment; do not set Development on an externally reachable installation to turn Swagger back on.

When to Use It

• Verify available endpoints and expected payloads.
• Quick debugging of request/response during frontend integration.
• Check API routes after scaffolding, refactoring, or metadata update.

Relationship with Metadata and Scaffolding

• After initial setup, it is advisable to validate the main endpoints from Swagger to confirm that the active host is the correct one.
• In metadata-driven scenarios, Swagger helps verify technical endpoints (MetaService, custom APIs) used by routes.
• Useful references:

- Metadata

- Initial Scaffolding

Local Environment Note

• If frontend and backend run on different hosts/ports, the relative /swagger link works when you go through the correct gateway/proxy.
• Alternatively, use the absolute URL of the active backend instance (e.g., http://localhost:5000/swagger).