# Swagger Documentation

This document explains how to access and update the Swagger documentation for the Time Tracker API.

## Accessing Swagger UI

After starting the backend server, access the Swagger UI at:
```
http://localhost:8080/swagger/index.html
```

This interactive interface allows you to:
- Browse all available API endpoints
- See request parameters and response formats
- Test API calls directly from the browser

## Updating Swagger Documentation

To update the Swagger documentation for the Time Tracker API, follow these steps:

1. **Add or update Swagger annotations in your code**
   - Annotations should be added as comments above handler functions
   - Use the correct types in annotations (e.g., `dto.ActivityDto` instead of `utils.ActivityResponse`)
   - Make sure all parameters, responses, and types are properly documented

2. **Run the Swagger generation command**
   ```bash
   cd backend && swag init -g cmd/api/main.go --output docs
   ```
   
   This command:
   - Uses `swag` CLI tool to parse your code
   - Looks for the main entry point in `cmd/api/main.go`
   - Outputs the generated files to the `docs` directory

3. **Verify the generated files**
   The command will generate or update three files:
   - `docs/docs.go` - Go code for the Swagger documentation
   - `docs/swagger.json` - JSON representation of the API
   - `docs/swagger.yaml` - YAML representation of the API

4. **Common issues and solutions**
   - If you encounter "cannot find type definition" errors, check that you're using the correct type names in your annotations
   - If endpoints are missing, ensure they have proper Swagger annotations
   - If you change the base path or other global settings, update them in the `main.go` file annotations

## Swagger Annotation Examples

### Main API Information

In `main.go`:
```go
//	@title						Time Tracker API
//	@version					1.0
//	@description				This is a simple time tracker API.
//	@host						localhost:8080
//	@BasePath					/api
//	@securityDefinitions.apikey	BearerAuth
//	@in							header
//	@name						Authorization
```

### Endpoint Documentation

Example from a handler function:
```go
// GetActivities handles GET /activities
//
//	@Summary		Get all activities
//	@Description	Get a list of all activities
//	@Tags			activities
//	@Accept			json
//	@Produce		json
//	@Security		BearerAuth
//	@Success		200	{object}	utils.Response{data=[]dto.ActivityDto}
//	@Failure		401	{object}	utils.Response{error=utils.ErrorInfo}
//	@Failure		500	{object}	utils.Response{error=utils.ErrorInfo}
//	@Router			/activities [get]
func (h *ActivityHandler) GetActivities(c *gin.Context) {
    // Function implementation
}
```

Remember that the Swagger documentation is generated from the annotations in your code, so keeping these annotations up-to-date is essential for accurate API documentation.