85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# 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.
|