{ "openapi": "3.0.3", "info": { "title": "timeTracker API", "description": "Authentication and user management API", "version": "1.0.0", "contact": { "name": "API Support", "email": "support@example.com" } }, "servers": [ { "url": "http://localhost:3000", "description": "Development server" } ], "tags": [ { "name": "Health", "description": "Health check endpoints" }, { "name": "Auth", "description": "Authentication endpoints" }, { "name": "Languages", "description": "Language and translation endpoints" }, { "name": "Protected", "description": "Protected routes requiring authentication" }, { "name": "Admin", "description": "Admin-only endpoints" }, { "name": "Settings", "description": "Application settings and configuration endpoints" } ], "paths": { "/health": { "get": { "tags": ["Health"], "summary": "Health check", "description": "Returns the health status of the application", "operationId": "getHealth", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "app": { "type": "string", "example": "timeTracker" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } }, "/api/v1/langs": { "get": { "tags": ["Languages"], "summary": "Get active languages", "description": "Returns a list of all active languages", "operationId": "getLanguages", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } } } } } } }, "/api/v1/translations": { "get": { "tags": ["Languages"], "summary": "Get translations", "description": "Returns translations from cache. Supports filtering by lang_id, scope, and components.", "operationId": "getTranslations", "parameters": [ { "name": "lang_id", "in": "query", "description": "Filter by language ID", "required": false, "schema": { "type": "integer" } }, { "name": "scope", "in": "query", "description": "Filter by scope (e.g., 'be', 'frontend')", "required": false, "schema": { "type": "string" } }, { "name": "components", "in": "query", "description": "Filter by component name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "translations": { "type": "object", "description": "Translation data keyed by language ID, scope, component, and key" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/translations/reload": { "get": { "tags": ["Languages"], "summary": "Reload translations", "description": "Reloads translations from the database into the cache", "operationId": "reloadTranslations", "responses": { "200": { "description": "Translations reloaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Translations reloaded successfully" } } } } } }, "500": { "description": "Failed to reload translations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": ["Auth"], "summary": "User login", "description": "Authenticate a user with email and password", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } }, "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "HTTP-only cookies containing access and refresh tokens" } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account inactive or email not verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/register": { "post": { "tags": ["Auth"], "summary": "User registration", "description": "Register a new user account", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "registration successful, please verify your email" } } } } } }, "400": { "description": "Invalid request or email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/complete-registration": { "post": { "tags": ["Auth"], "summary": "Complete registration", "description": "Complete registration after email verification", "operationId": "completeRegistration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRegistrationRequest" } } } }, "responses": { "201": { "description": "Registration completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": ["Auth"], "summary": "Request password reset", "description": "Request a password reset email", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "description": "User's email address" } } } } } }, "responses": { "200": { "description": "Password reset email sent if account exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "if an account with that email exists, a password reset link has been sent" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/reset-password": { "post": { "tags": ["Auth"], "summary": "Reset password", "description": "Reset password using reset token", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "password reset successfully" } } } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": ["Auth"], "summary": "User logout", "description": "Clear authentication cookies", "operationId": "logout", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "logged out successfully" } } } } } } } } }, "/api/v1/auth/refresh": { "post": { "tags": ["Auth"], "summary": "Refresh access token", "description": "Get a new access token using refresh token", "operationId": "refreshToken", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "Refresh token from login response" } } } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Refresh token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or expired refresh token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/protected/dashboard": { "get": { "tags": ["Protected"], "summary": "Get dashboard data", "description": "Protected route requiring authentication", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Dashboard data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserSession" } } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/users": { "get": { "tags": ["Admin"], "summary": "Get all users", "description": "Admin-only endpoint for user management", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/settings": { "get": { "tags": ["Settings"], "summary": "Get application settings", "description": "Returns public application settings and configuration", "operationId": "getSettings", "responses": { "200": { "description": "Settings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } } } } } }, "components": { "schemas": { "LoginRequest": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email", "description": "User's email address" }, "password": { "type": "string", "format": "password", "description": "User's password" } } }, "RegisterRequest": { "type": "object", "required": ["email", "password", "confirm_password"], "properties": { "email": { "type": "string", "format": "email", "description": "User's email address" }, "password": { "type": "string", "format": "password", "description": "User's password (min 8 chars, uppercase, lowercase, digit)" }, "confirm_password": { "type": "string", "format": "password", "description": "Password confirmation" }, "first_name": { "type": "string", "description": "User's first name" }, "last_name": { "type": "string", "description": "User's last name" }, "lang": { "type": "string", "description": "User's preferred language (e.g., 'en', 'pl', 'cs')" } } }, "CompleteRegistrationRequest": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string", "description": "Email verification token" } } }, "ResetPasswordRequest": { "type": "object", "required": ["token", "password"], "properties": { "token": { "type": "string", "description": "Password reset token" }, "password": { "type": "string", "format": "password", "description": "New password" } } }, "AuthResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT access token" }, "refresh_token": { "type": "string", "description": "JWT refresh token" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Token expiration in seconds" }, "user": { "$ref": "#/components/schemas/UserSession" } } }, "UserSession": { "type": "object", "properties": { "user_id": { "type": "integer", "format": "uint", "description": "User ID" }, "email": { "type": "string", "format": "email" }, "username": { "type": "string" }, "role": { "type": "string", "enum": ["user", "admin"], "description": "User role" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "Language": { "type": "object", "properties": { "id": { "type": "integer", "format": "uint64", "description": "Language ID" }, "name": { "type": "string", "description": "Language name" }, "iso_code": { "type": "string", "description": "ISO 639-1 code (e.g., 'en', 'pl')" }, "lang_code": { "type": "string", "description": "Full language code (e.g., 'en-US', 'pl-PL')" }, "date_format": { "type": "string", "description": "Date format string" }, "date_format_short": { "type": "string", "description": "Short date format string" }, "rtl": { "type": "boolean", "description": "Right-to-left language" }, "is_default": { "type": "boolean", "description": "Is default language" }, "active": { "type": "boolean", "description": "Is active" }, "flag": { "type": "string", "description": "Flag emoji or code" } } }, "SettingsResponse": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppSettings" }, "server": { "$ref": "#/components/schemas/ServerSettings" }, "auth": { "$ref": "#/components/schemas/AuthSettings" }, "features": { "$ref": "#/components/schemas/FeatureFlags" }, "version": { "$ref": "#/components/schemas/VersionInfo" } } }, "AppSettings": { "type": "object", "properties": { "name": { "type": "string", "description": "Application name" }, "environment": { "type": "string", "description": "Application environment (e.g., 'development', 'production')" }, "base_url": { "type": "string", "description": "Base URL of the application" } } }, "ServerSettings": { "type": "object", "properties": { "port": { "type": "integer", "description": "Server port" }, "host": { "type": "string", "description": "Server host" } } }, "AuthSettings": { "type": "object", "properties": { "jwt_expiration": { "type": "integer", "description": "JWT token expiration in seconds" }, "refresh_expiration": { "type": "integer", "description": "Refresh token expiration in seconds" } } }, "FeatureFlags": { "type": "object", "properties": { "email_enabled": { "type": "boolean", "description": "Whether email functionality is enabled" }, "oauth_google": { "type": "boolean", "description": "Whether Google OAuth is enabled" } } }, "VersionInfo": { "type": "object", "properties": { "version": { "type": "string", "description": "Application version" }, "commit": { "type": "string", "description": "Git commit hash" }, "date": { "type": "string", "description": "Build date" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from login response" } } } }