tm_back/docs/setup/SWAGGER_SETUP.md

Swagger API Documentation Setup

This document explains how to use and maintain the Swagger API documentation for the Tender Management Backend.

📚 Overview

The API documentation is generated using Swag and served using echo-swagger. The documentation provides an interactive interface to explore and test all API endpoints.

🚀 Quick Start

1. Generate Documentation

# Generate Swagger documentation
make docs

# Or manually
swag init -g cmd/web/main.go -o cmd/web/docs

2. Start Server with Documentation

# Build and run with documentation
make run-docs

# Or manually
make build
./bin/web

3. Access Documentation

Open your browser and navigate to:

• Swagger UI: http://localhost:8081/swagger/index.html
• Health Check: http://localhost:8081/health

📋 Available Endpoints

🔐 Authentication

• POST /api/customers/login - Customer login
• POST /api/customers/refresh-token - Refresh access token

👤 Customer Profile (Protected)

• GET /api/customers/profile - Get customer profile
• PUT /api/customers/profile - Update customer profile
• PUT /api/customers/change-password - Change password

📱 Device Management (Protected)

• POST /api/customers/device-token - Add device token
• DELETE /api/customers/device-token - Remove device token

👥 Admin Operations (Admin Protected)

• POST /api/admin/customers/register - Register new customer
• GET /api/admin/customers - List customers
• GET /api/admin/customers/{id} - Get customer by ID
• PUT /api/admin/customers/{id}/status - Update customer status

🛠️ Development

Adding New Endpoints

1. Add Swagger Annotations to your handler functions:

// @Summary Endpoint summary
// @Description Detailed description
// @Tags tag-name
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param param-name param-type param-required "param description"
// @Success 200 {object} response.APIResponse{data=YourResponseType} "Success description"
// @Failure 400 {object} response.APIResponse "Error description"
// @Router /api/endpoint [method]
func (h *Handler) YourHandler(c echo.Context) error {
    // Your handler implementation
}

2. Regenerate Documentation:

make docs

Swagger Annotation Examples

Basic GET Endpoint

// @Summary Get resource
// @Description Get a resource by ID
// @Tags resources
// @Accept json
// @Produce json
// @Param id path string true "Resource ID"
// @Success 200 {object} response.APIResponse{data=ResourceResponse}
// @Failure 404 {object} response.APIResponse
// @Router /api/resources/{id} [get]

POST with Request Body

// @Summary Create resource
// @Description Create a new resource
// @Tags resources
// @Accept json
// @Produce json
// @Param resource body CreateResourceForm true "Resource data"
// @Success 201 {object} response.APIResponse{data=ResourceResponse}
// @Failure 400 {object} response.APIResponse
// @Router /api/resources [post]

Protected Endpoint

// @Summary Protected endpoint
// @Description This endpoint requires authentication
// @Tags resources
// @Accept json
// @Produce json
// @Security BearerAuth
// @Success 200 {object} response.APIResponse
// @Failure 401 {object} response.APIResponse
// @Router /api/protected [get]

📁 File Structure

cmd/web/
├── main.go          # Main application entry point
├── bootstrap.go     # Server initialization
└── docs/           # Generated Swagger documentation
    ├── docs.go     # Generated docs
    ├── swagger.json # OpenAPI specification
    └── swagger.yaml # OpenAPI specification (YAML)

internal/customer/
├── handler.go      # HTTP handlers with Swagger annotations
├── form.go         # Request/response forms
└── ...

pkg/response/
└── response.go     # Standard API response types

🔧 Configuration

Swagger Configuration

The main Swagger configuration is in cmd/web/docs.go:

// @title Tender Management API
// @version 1.0.0
// @description This is the API documentation for the Tender Management System.
// @host localhost:8081
// @BasePath /api/v1
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization

Server Configuration

The Swagger endpoint is registered in cmd/web/bootstrap.go:

// Add Swagger documentation endpoint
e.GET("/swagger/*", echoSwagger.WrapHandler)

🧪 Testing

Using the Test Script

# Run the test script
./test_swagger.sh

This script will:

1. Build the application
2. Start the server
3. Display all available endpoints
4. Provide access URLs

Manual Testing

1. Start the server:

   make run-docs
   

2. Access Swagger UI:

   • Open http://localhost:8081/swagger/index.html
   • Explore and test endpoints interactively

3. Test Health Check:

   curl http://localhost:8081/health
   

📝 Response Types

Standard Response Structure

All API responses follow this structure:

{
  "success": true,
  "message": "Operation successful",
  "data": {
    // Response data
  },
  "meta": {
    // Pagination metadata (if applicable)
  },
  "error": {
    // Error details (if applicable)
  }
}

Error Response

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "ERROR_CODE",
    "message": "Detailed error message",
    "details": "Additional details"
  }
}

🔐 Authentication

Bearer Token Authentication

Most endpoints require Bearer token authentication:

1. Login to get access token:

   curl -X POST http://localhost:8081/api/customers/login \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com", "password": "password"}'
   

2. Use the token in subsequent requests:

   curl -X GET http://localhost:8081/api/customers/profile \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

🚨 Troubleshooting

Common Issues

1. Documentation not updating:

   make clean
   make docs
   make build
   

2. Swagger annotations not recognized:

   • Ensure annotations are directly above the function
   • Check for syntax errors in annotations
   • Verify import paths are correct

3. Server won't start:

   • Check if port 8081 is available
   • Verify MongoDB connection
   • Check configuration files

Debug Commands

# Check if swag is installed
swag --version

# Generate docs with verbose output
swag init -g cmd/web/main.go -o cmd/web/docs --parseDependency

# Check generated files
ls -la cmd/web/docs/

📚 Additional Resources

• Swag Documentation
• Echo Swagger
• OpenAPI Specification
• Swagger UI

🤝 Contributing

When adding new endpoints:

1. Add comprehensive Swagger annotations
2. Include all possible response codes
3. Provide meaningful examples
4. Test the documentation in Swagger UI
5. Update this documentation if needed

📄 License

This documentation is part of the Tender Management Backend project.