945 lines
25 KiB
JSON
945 lines
25 KiB
JSON
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|