Add Swag annotations to all handler endpoints for OpenAPI documentation

2026-05-18 21:50:53 +02:00
parent fabd6a6931
commit e57609725e
7 changed files with 2287 additions and 0 deletions
@@ -14,18 +14,41 @@ func NewDownloadHandler() *DownloadHandler {
 	return &DownloadHandler{}
 }

+// CheckLatest godoc
+// @Summary Check for latest version
+// @Description Checks for the latest version of the application
+// @Tags download
+// @Accept json
+// @Produce json
+// @Success 200 {string} string
+// @Router /download [get]
 func (d *DownloadHandler) checkLatest(ctx echo.Context) error {
 	log.Println("Checking latest version")
 	latest := backend.CheckLatest()
 	return ctx.JSON(http.StatusOK, latest)
 }

+// ListAssetsOfLatest godoc
+// @Summary List assets of latest version
+// @Description Lists all assets available for the latest version
+// @Tags download
+// @Accept json
+// @Produce json
+// @Success 200 {array} string
+// @Router /download/list [get]
 func (d *DownloadHandler) listAssetsOfLatest(ctx echo.Context) error {
 	log.Println("Listing assets")
 	assets := backend.ListAssetsOfLatest()
 	return ctx.JSON(http.StatusOK, assets)
 }

+// DownloadLatestWindows godoc
+// @Summary Download latest Windows version
+// @Description Redirects to download the latest Windows version
+// @Tags download
+// @Produce octet-stream
+// @Success 302 {string} string
+// @Router /download/windows [get]
 func (d *DownloadHandler) downloadLatestWindows(ctx echo.Context) error {
 	log.Println("Downloading latest windows")
 	asset := backend.DownloadLatestWindows()
@@ -33,6 +56,13 @@ func (d *DownloadHandler) downloadLatestWindows(ctx echo.Context) error {
 	return ctx.Redirect(http.StatusFound, asset)
 }

+// DownloadLatestLinux godoc
+// @Summary Download latest Linux version
+// @Description Redirects to download the latest Linux version
+// @Tags download
+// @Produce octet-stream
+// @Success 302 {string} string
+// @Router /download/linux [get]
 func (d *DownloadHandler) downloadLatestLinux(ctx echo.Context) error {
 	log.Println("Downloading latest linux")
 	asset := backend.DownloadLatestLinux()
@@ -33,20 +33,53 @@ func (i *IndexHandler) GetVersion(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, versionHistory)
 }

+// GetDBTest godoc
+// @Summary Test database connection
+// @Description Tests the database connection
+// @Tags database
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "TestedDB"
+// @Router /dbtest [get]
 func (i *IndexHandler) GetDBTest(ctx echo.Context) error {
 	backend.TestDB()
 	return ctx.JSON(http.StatusOK, "TestedDB")
 }

+// HealthCheck godoc
+// @Summary Check server health
+// @Description Returns the health status of the server
+// @Tags health
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "OK"
+// @Router /health [get]
 func (i *IndexHandler) HealthCheck(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, db.Health())
 }

+// GetCharacterList godoc
+// @Summary Get list of characters
+// @Description Returns a list of all available characters
+// @Tags characters
+// @Accept json
+// @Produce json
+// @Success 200 {array} string
+// @Router /characters [get]
 func (i *IndexHandler) GetCharacterList(ctx echo.Context) error {
 	characters := backend.GetCharacterList()
 	return ctx.JSON(http.StatusOK, characters)
 }

+// GetCharacter godoc
+// @Summary Get character image
+// @Description Returns the image for a specific character
+// @Tags characters
+// @Accept json
+// @Produce image/png
+// @Param name query string true "Character name"
+// @Success 200 {file} file
+// @Router /character [get]
 func (i *IndexHandler) GetCharacter(ctx echo.Context) error {
 	character := ctx.QueryParam("name")
 	return ctx.File(backend.GetCharacter(character))
@@ -17,6 +17,18 @@ func NewMusicHandler() *MusicHandler {
 	return &MusicHandler{}
 }

+// GetSong godoc
+// @Summary Get a specific song
+// @Description Returns a specific song by name
+// @Tags music
+// @Accept json
+// @Produce audio/mpeg
+// @Param song query string true "Song name"
+// @Success 200 {file} file
+// @Failure 400 {string} string "song can't be empty"
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music [get]
 func (m *MusicHandler) GetSong(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -35,6 +47,15 @@ func (m *MusicHandler) GetSong(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetSoundCheckSong godoc
+// @Summary Get sound check song
+// @Description Returns the sound check song
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/soundTest [get]
 func (m *MusicHandler) GetSoundCheckSong(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -49,6 +70,14 @@ func (m *MusicHandler) GetSoundCheckSong(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// ResetMusic godoc
+// @Summary Reset music state
+// @Description Resets the music state
+// @Tags music
+// @Accept json
+// @Success 204
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/reset [get]
 func (m *MusicHandler) ResetMusic(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -58,6 +87,15 @@ func (m *MusicHandler) ResetMusic(ctx echo.Context) error {
 	return ctx.NoContent(http.StatusOK)
 }

+// GetRandomSong godoc
+// @Summary Get random song
+// @Description Returns a random song
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/rand [get]
 func (m *MusicHandler) GetRandomSong(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -72,6 +110,15 @@ func (m *MusicHandler) GetRandomSong(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetRandomSongLowChance godoc
+// @Summary Get random song with low chance
+// @Description Returns a random song with low chance selection
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/rand/low [get]
 func (m *MusicHandler) GetRandomSongLowChance(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -86,6 +133,15 @@ func (m *MusicHandler) GetRandomSongLowChance(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetRandomSongClassic godoc
+// @Summary Get random classic song
+// @Description Returns a random song from the classic selection
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/rand/classic [get]
 func (m *MusicHandler) GetRandomSongClassic(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -100,16 +156,41 @@ func (m *MusicHandler) GetRandomSongClassic(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetSongInfo godoc
+// @Summary Get current song info
+// @Description Returns information about the current song
+// @Tags music
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /music/info [get]
 func (m *MusicHandler) GetSongInfo(ctx echo.Context) error {
 	song := backend.GetSongInfo()
 	return ctx.JSON(http.StatusOK, song)
 }

+// GetPlayedSongs godoc
+// @Summary Get played songs list
+// @Description Returns a list of played songs
+// @Tags music
+// @Accept json
+// @Produce json
+// @Success 200 {array} map[string]interface{}
+// @Router /music/list [get]
 func (m *MusicHandler) GetPlayedSongs(ctx echo.Context) error {
 	songList := backend.GetPlayedSongs()
 	return ctx.JSON(http.StatusOK, songList)
 }

+// GetNextSong godoc
+// @Summary Get next song
+// @Description Returns the next song in the queue
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/next [get]
 func (m *MusicHandler) GetNextSong(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -124,6 +205,15 @@ func (m *MusicHandler) GetNextSong(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetPreviousSong godoc
+// @Summary Get previous song
+// @Description Returns the previous song in the queue
+// @Tags music
+// @Produce audio/mpeg
+// @Success 200 {file} file
+// @Failure 404 {string} string "Not Found"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/previous [get]
 func (m *MusicHandler) GetPreviousSong(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -138,6 +228,15 @@ func (m *MusicHandler) GetPreviousSong(ctx echo.Context) error {
 	return ctx.Stream(http.StatusOK, "audio/mpeg", file)
 }

+// GetAllGames godoc
+// @Summary Get all games
+// @Description Returns a list of all games in order
+// @Tags music
+// @Accept json
+// @Produce json
+// @Success 200 {array} map[string]interface{}
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/all/order [get]
 func (m *MusicHandler) GetAllGames(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -147,6 +246,15 @@ func (m *MusicHandler) GetAllGames(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, gameList)
 }

+// GetAllGamesRandom godoc
+// @Summary Get all games random
+// @Description Returns a list of all games in random order
+// @Tags music
+// @Accept json
+// @Produce json
+// @Success 200 {array} map[string]interface{}
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/all/random [get]
 func (m *MusicHandler) GetAllGamesRandom(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -156,6 +264,17 @@ func (m *MusicHandler) GetAllGamesRandom(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, gameList)
 }

+// PutPlayed godoc
+// @Summary Mark song as played
+// @Description Marks a song as played by its ID
+// @Tags music
+// @Accept json
+// @Produce json
+// @Param song query int true "Song ID"
+// @Success 204
+// @Failure 400 {string} string "Bad Request"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/played [put]
 func (m *MusicHandler) PutPlayed(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -170,6 +289,14 @@ func (m *MusicHandler) PutPlayed(ctx echo.Context) error {
 	return ctx.NoContent(http.StatusOK)
 }

+// AddLatestToQue godoc
+// @Summary Add latest to queue
+// @Description Adds the latest song to the queue
+// @Tags music
+// @Accept json
+// @Success 204
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/addQue [get]
 func (m *MusicHandler) AddLatestToQue(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -179,6 +306,14 @@ func (m *MusicHandler) AddLatestToQue(ctx echo.Context) error {
 	return ctx.NoContent(http.StatusOK)
 }

+// AddLatestPlayed godoc
+// @Summary Add latest to played
+// @Description Adds the latest song to the played list
+// @Tags music
+// @Accept json
+// @Success 204
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /music/addPlayed [get]
 func (m *MusicHandler) AddLatestPlayed(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -15,6 +15,14 @@ func NewSyncHandler() *SyncHandler {
 	return &SyncHandler{}
 }

+// SyncProgress godoc
+// @Summary Get sync progress
+// @Description Returns the current sync progress or result
+// @Tags sync
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /sync/progress [get]
 func (s *SyncHandler) SyncProgress(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Getting progress")
@@ -26,6 +34,15 @@ func (s *SyncHandler) SyncProgress(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, response)
 }

+// SyncGamesNewOnlyChanges godoc
+// @Summary Sync games with only changes
+// @Description Starts syncing games with only new changes
+// @Tags sync
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "Start syncing games"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /sync [get]
 func (s *SyncHandler) SyncGamesNewOnlyChanges(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -36,6 +53,15 @@ func (s *SyncHandler) SyncGamesNewOnlyChanges(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, "Start syncing games")
 }

+// SyncGamesNewFull godoc
+// @Summary Sync all games fully
+// @Description Starts a full sync of all games
+// @Tags sync
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "Start syncing games full"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /sync/full [get]
 func (s *SyncHandler) SyncGamesNewFull(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")
@@ -46,6 +72,15 @@ func (s *SyncHandler) SyncGamesNewFull(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, "Start syncing games full")
 }

+// ResetGames godoc
+// @Summary Reset games database
+// @Description Resets the games database by deleting all games and songs
+// @Tags sync
+// @Accept json
+// @Produce json
+// @Success 200 {string} string "Games and songs are deleted from the database"
+// @Failure 423 {string} string "Syncing is in progress"
+// @Router /sync/reset [get]
 func (s *SyncHandler) ResetGames(ctx echo.Context) error {
 	if backend.Syncing {
 		log.Println("Syncing is in progress")