feat: Enhance OAuth2 handlers and user authentication endpoints

- Added Swagger documentation for Google, Facebook, and GitHub OAuth2 login and callback handlers.
- Improved error handling in user registration and login by using structured error responses.
- Introduced new endpoints for refreshing tokens, requesting password resets, and verifying emails with appropriate documentation.
- Updated user profile retrieval to return structured user response.
- Added DTOs for error and message responses to standardize API responses.

Author: gjovanovicst

README.md

@@ -12,6 +12,7 @@ A modern, production-ready Go REST API for authentication and authorization, fea
 - Redis for token/session management
 - Dockerized for local development & deployment
 - Unit & integration tests
+- **Interactive Swagger API documentation**
 
 ## 🗂️ Project Structure
 ```
@@ -22,6 +23,23 @@ pkg/                    # Models, DTOs, errors, JWT helpers
 Dockerfile, docker-compose.yml, dev.sh, dev.bat
 ```
 
+## 📖 API Documentation (Swagger)
+After starting the server, access the interactive API docs at:
+
+- [http://localhost:8080/swagger/index.html](http://localhost:8080/swagger/index.html)
+
+You can try out all endpoints, including social logins, directly from the browser.
+
+## 🔄 Regenerating Swagger Documentation
+If you make changes to your API routes or annotations, regenerate the Swagger docs with:
+
+```
+swag init -g cmd/api/main.go -o docs
+```
+
+- Requires the [swag CLI](https://github.com/swaggo/swag) (`go install github.com/swaggo/swag/cmd/swag@latest`)
+- This will update the `docs/` folder with the latest API documentation
+
 ## ⚡ Quick Start (Docker)
 1. Clone the repository
 2. Copy `.env` and update with your credentials

cmd/api/main.go

@@ -8,14 +8,37 @@ import (
 	"github.com/joho/godotenv"
 	"github.com/spf13/viper"
 
+	_ "github.com/gjovanovicst/auth_api/docs" // docs is generated by Swag CLI
 	"github.com/gjovanovicst/auth_api/internal/database"
 	"github.com/gjovanovicst/auth_api/internal/email"
 	"github.com/gjovanovicst/auth_api/internal/middleware"
 	"github.com/gjovanovicst/auth_api/internal/redis"
 	"github.com/gjovanovicst/auth_api/internal/social"
 	"github.com/gjovanovicst/auth_api/internal/user"
+	swaggerFiles "github.com/swaggo/files"
+	ginSwagger "github.com/swaggo/gin-swagger"
 )
 
+// @title           Authentication and Authorization API
+// @version         1.0
+// @description     This is a sample authentication and authorization API built with Go and Gin.
+// @termsOfService  http://swagger.io/terms/
+
+// @contact.name   API Support
+// @contact.url    http://www.swagger.io/support
+// @contact.email  [email protected]
+
+// @license.name  Apache 2.0
+// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
+
+// @host      localhost:8080
+// @BasePath  /
+
+// @securityDefinitions.apikey ApiKeyAuth
+// @in header
+// @name Authorization
+// @description Type "Bearer" + your JWT token
+
 func main() {
 	// Load environment variables from .env file
 	if err := godotenv.Load(); err != nil {
@@ -84,6 +107,9 @@ func main() {
 		// Add other protected routes here
 	}
 
+	// Add Swagger UI endpoint
+	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+
 	// Start the server
 	port := viper.GetString("PORT")
 	log.Printf("Server starting on port %s", port)