feat: Setup Swagger API documentation for backend (#120)

* feat: Setup Swagger API documentation for backend

- Added swaggo/swag package for automated API documentation
- Implemented Swagger annotations for all API endpoints:
  * Task management endpoints (get, add, edit, modify, complete, delete)
  * Authentication endpoints (OAuth, callback, user info, logout)
- Added Swagger UI endpoint at /swagger/index.html
- Updated go.mod with required dependencies (swaggo/swag, http-swagger)
- Generated comprehensive API documentation
- Created setup guides (SWAGGER_SETUP.md, QUICK_START.md)
Benefits:
- Auto-generated, always up-to-date API documentation
- Interactive testing interface replacing Postman collection
- Industry-standard OpenAPI/Swagger specification
Closes #118

* Address PR review feedback for Swagger implementation

- Remove auto-generated documentation files (IMPLEMENTATION_SUMMARY.md, QUICK_START.md, SWAGGER_SETUP.md)
- Remove incorrect email address (support@ccsync.com) from swagger.json, swagger.yaml, and main.go
- Update misleading comment in main.go about docs generation
- Change Swagger endpoint from /swagger/ to /api/docs/ for better convention
- Add API documentation section to backend README with endpoint URL

* Regenerate swagger docs to remove email address

- Run swag init to regenerate docs.go without support@ccsync.com
- This fixes the auto-generated file to match main.go annotations

* Fix formatting issues (gofmt and prettier)

- Run gofmt on backend Go files
- Run prettier on all project files
- This fixes the failing CI checks

* Trigger CI checks re-run

Author: Eshaan-byte

.github/workflows/backend-test.yml

@@ -12,7 +12,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.21.x'
+          go-version: "1.21.x"
       - name: Install dependencies
         run: go get .
         working-directory: backend

.github/workflows/docker.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
       - name: Checkout repository code
         uses: actions/checkout@v4
-      
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 

.github/workflows/prettier.yml

@@ -5,7 +5,7 @@ on:
       - "main"
   pull_request:
     branches:
-      - "main" 
+      - "main"
       - "dev"
 jobs:
   prettier:

CONTRIBUTING.md

@@ -25,7 +25,6 @@ Scan through our [existing issues](https://github.com/its-me-abhishek/ccsync/iss
 1. Fork the repository.
 
 - Using GitHub Desktop:
-
   - [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
   - Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
 

backend/README.md

@@ -55,3 +55,11 @@
   docker-compose build backend
   docker-compose up
   ```
+
+## API Documentation
+
+Once the backend server is running, you can view the interactive API documentation (Swagger UI) at:
+
+- **Local development**: http://localhost:8000/api/docs/index.html
+
+The documentation provides detailed information about all available endpoints, request/response schemas, and allows you to test the API directly from your browser.

backend/controllers/add_task.go

@@ -11,6 +11,17 @@ import (
 
 var GlobalJobQueue *JobQueue
 
+// AddTaskHandler godoc
+// @Summary Add a new task
+// @Description Add a new task to Taskwarrior for a specific user
+// @Tags Tasks
+// @Accept json
+// @Produce json
+// @Param task body models.AddTaskRequestBody true "Task details"
+// @Success 202 {string} string "Task accepted for processing"
+// @Failure 400 {string} string "Bad request - invalid input or missing required fields"
+// @Failure 405 {string} string "Method not allowed"
+// @Router /add-task [post]
 func AddTaskHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodPost {
 		body, err := io.ReadAll(r.Body)

backend/controllers/app_handlers.go

@@ -20,12 +20,30 @@ type App struct {
 	UUID             string
 }
 
+// OAuthHandler godoc
+// @Summary Initiate OAuth login
+// @Description Redirects user to Google OAuth login page
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Success 307 {string} string "Redirect to OAuth provider"
+// @Router /auth/oauth [get]
 func (a *App) OAuthHandler(w http.ResponseWriter, r *http.Request) {
 	url := a.Config.AuthCodeURL("state", oauth2.AccessTypeOffline)
 	http.Redirect(w, r, url, http.StatusTemporaryRedirect)
 }
 
-// fetching the info
+// OAuthCallbackHandler godoc
+// @Summary OAuth callback handler
+// @Description Handles the OAuth callback and creates user session
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param code query string true "OAuth authorization code"
+// @Success 303 {string} string "Redirect to frontend home page"
+// @Failure 400 {string} string "Bad request"
+// @Failure 500 {string} string "Internal server error"
+// @Router /auth/callback [get]
 func (a *App) OAuthCallbackHandler(w http.ResponseWriter, r *http.Request) {
 	log.Println("Fetching user info...")
 
@@ -75,6 +93,15 @@ func (a *App) OAuthCallbackHandler(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, frontendOriginDev+"/home", http.StatusSeeOther)
 }
 
+// UserInfoHandler godoc
+// @Summary Get user information
+// @Description Retrieve user information from the session
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{} "User information including email, id, uuid, and encryption_secret"
+// @Failure 401 {string} string "No user info available - user not authenticated"
+// @Router /api/user [get]
 func (a *App) UserInfoHandler(w http.ResponseWriter, r *http.Request) {
 	session, _ := a.SessionStore.Get(r, "session-name")
 	userInfo, ok := session.Values["user"].(map[string]interface{})
@@ -103,7 +130,15 @@ func (a *App) EnableCORS(handler http.Handler) http.Handler {
 	})
 }
 
-// logout and delete session
+// LogoutHandler godoc
+// @Summary Logout user
+// @Description Logout user and delete session
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "Successfully logged out"
+// @Failure 500 {string} string "Internal server error"
+// @Router /auth/logout [get]
 func (a *App) LogoutHandler(w http.ResponseWriter, r *http.Request) {
 	session, _ := a.SessionStore.Get(r, "session-name")
 	session.Options.MaxAge = -1

backend/controllers/complete_task.go

@@ -9,6 +9,17 @@ import (
 	"net/http"
 )
 
+// CompleteTaskHandler godoc
+// @Summary Complete a task
+// @Description Mark a task as completed in Taskwarrior
+// @Tags Tasks
+// @Accept json
+// @Produce json
+// @Param task body models.CompleteTaskRequestBody true "Task completion details"
+// @Success 202 {string} string "Task completion accepted for processing"
+// @Failure 400 {string} string "Bad request - invalid input or missing taskuuid"
+// @Failure 405 {string} string "Method not allowed"
+// @Router /complete-task [post]
 func CompleteTaskHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodPost {
 		body, err := io.ReadAll(r.Body)

backend/controllers/delete_task.go

@@ -9,6 +9,17 @@ import (
 	"net/http"
 )
 
+// DeleteTaskHandler godoc
+// @Summary Delete a task
+// @Description Delete a task from Taskwarrior
+// @Tags Tasks
+// @Accept json
+// @Produce json
+// @Param task body models.DeleteTaskRequestBody true "Task deletion details"
+// @Success 202 {string} string "Task deletion accepted for processing"
+// @Failure 400 {string} string "Bad request - invalid input or missing taskuuid"
+// @Failure 405 {string} string "Method not allowed"
+// @Router /delete-task [post]
 func DeleteTaskHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodPost {
 		body, err := io.ReadAll(r.Body)

backend/controllers/edit_task.go

@@ -9,6 +9,17 @@ import (
 	"net/http"
 )
 
+// EditTaskHandler godoc
+// @Summary Edit a task
+// @Description Edit task description and tags in Taskwarrior
+// @Tags Tasks
+// @Accept json
+// @Produce json
+// @Param task body models.EditTaskRequestBody true "Task edit details"
+// @Success 202 {string} string "Task edit accepted for processing"
+// @Failure 400 {string} string "Bad request - invalid input or missing taskID"
+// @Failure 405 {string} string "Method not allowed"
+// @Router /edit-task [post]
 func EditTaskHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodPost {
 		body, err := io.ReadAll(r.Body)