Sansan/MusicServer
1
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

Add Swag annotations to all handler endpoints for OpenAPI documentation

Browse Source
This commit is contained in:
Sebastian
2026-05-18 21:50:53 +02:00
parent fabd6a6931
commit e57609725e
7 changed files with 2287 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/server/musicHandler.go
+135
View File
@@ -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")