time-tracker/docu/swagger_documentation.md

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

   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:

//	@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:

// 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.