manicanldes-backend/docs/swagger.md

API explorer

Start the backend with the existing database configuration (pnpm build, then pnpm start). In development, open http://localhost:3000/api/docs. The machine-readable OpenAPI specification is at /api/docs-json. If PORT differs, use that port.

1. Bootstrap an owner using the setup instructions in README, or use an existing account.
2. Expand Auth and execute POST /api/v1/auth/login with your organization UUID, email and password.
3. Copy accessToken from the successful response. Click Authorize, paste the token without a Bearer prefix and confirm.
4. Select an endpoint, click Try it out, fill its parameters/body and execute. Required permissions appear in the endpoint description. Requests use your real account permissions and can change data.
5. Log out through the API when finished and clear authorization in the UI.

The UI groups all registered controller routes. Request bodies, required fields, query defaults and constraints are derived from the same Zod schemas used by validation. Custom cross-field refinements and business rules still apply on the server. Successful response bodies are not yet exhaustively modeled; inspect actual responses. Errors share a documented envelope with distinct codes and a request ID for log correlation.

SWAGGER_ENABLED=true explicitly enables documentation; false disables it. If omitted, it is enabled only in development. Documentation itself does not require a session, so enable it on a deployed environment only when its API inventory should be visible there. Protected API operations still require authentication and permissions. Tokens are not persisted by Swagger across reloads. Assets are served locally and external schema validation is disabled.

Payment and shipping remain test blueprints. No gateway credentials or real integration are required by Swagger. No database schema changes or migrations are needed for this feature.