Commit dba4d34a authored by robwa's avatar robwa
Browse files

feat: Add API doc for files endpoints

parent cd10e239
......@@ -25,7 +25,7 @@ SWAG := swag
ifdef GOPATH
SWAG = $(GOPATH)/bin/swag
endif
SWAG_ARGS := -d api/v1/,./ -g api.go
SWAG_ARGS := -d api/v1/ -g api.go
EXECUTEABLE := tank
......@@ -41,9 +41,11 @@ format:
ui:
$(GOCMD) generate ./ui
api-docs:
fmt-api-docs:
$(SWAG) fmt $(SWAG_ARGS)
$(SWAG) init $(SWAG_ARGS) -o api/docs
api-docs:
$(SWAG) init $(SWAG_ARGS) --pd -o api/docs
build: ui
$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
......
This diff is collapsed.
......@@ -27,6 +27,17 @@ import (
"gitlab.servus.at/autoradio/tank/store"
)
// ListFilesOfShow returns a list of all files of the show.
// @Summary List files
// @Description Lists files of show
// @Produce json
// @Param name path string true "Name of the show"
// @Param limit query int false "Limit number of results"
// @Param offset query int false "Start listing from offset"
// @Success 200 {object} FilesListing
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files [get]
func (api *API) ListFilesOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -45,6 +56,19 @@ func (api *API) ListFilesOfShow(c *gin.Context) {
c.JSON(http.StatusOK, FilesListing{files})
}
// CreateFileForShow adds a file and starts import.
// @Summary Add file
// @Description Adds a file and starts import
// @Accept json
// @Produce json
// @Param name path string true "Name of the show"
// @Param file body FileCreateRequest true "URI of the file"
// @Param wait-for query string false "running|done - If given, return not before import has the given state"
// @Success 201 {object} store.File
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files [post]
func (api *API) CreateFileForShow(c *gin.Context) {
showID := c.Param("show-id")
authorized, sess := authorizeRequestForShow(c, showID)
......@@ -131,6 +155,17 @@ create_file_response:
c.JSON(status, errResp)
}
// ReadFileOfShow retrieves file object.
// @Summary Retrieve file
// @Description Retrieves file object.
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 200 {object} store.File
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id} [get]
func (api *API) ReadFileOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -150,6 +185,19 @@ func (api *API) ReadFileOfShow(c *gin.Context) {
c.JSON(http.StatusOK, file)
}
// PatchFileOfShow updates file metadata.
// @Summary Update file
// @Description Updates file metadata.
// @Accept json
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Param metadata body store.FileMetadata false "File metadata"
// @Success 200 {object} store.File
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id} [patch]
func (api *API) PatchFileOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -174,6 +222,16 @@ func (api *API) PatchFileOfShow(c *gin.Context) {
c.JSON(http.StatusOK, file)
}
// DeleteFileOfShow removes a file.
// @Summary Delete file
// @Description Removes a file.
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 204 {object} nil
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id} [delete]
func (api *API) DeleteFileOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -195,6 +253,17 @@ func (api *API) DeleteFileOfShow(c *gin.Context) {
c.JSON(http.StatusNoContent, nil)
}
// ReadUsageOfFile lists playlists referring to the file.
// @Summary List referring playlists
// @Description Lists playlists referring to the file.
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 200 {object} FileUsageListing
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/usage [get]
func (api *API) ReadUsageOfFile(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -214,6 +283,17 @@ func (api *API) ReadUsageOfFile(c *gin.Context) {
c.JSON(http.StatusOK, result)
}
// ReadLogsOfFile retrieves import logs of the file.
// @Summary Retrieve import logs
// @Description Retrieves import logs of the file.
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 200 {object} FileImportLogs
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/logs [get]
func (api *API) ReadLogsOfFile(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......
......@@ -24,6 +24,17 @@ import (
"github.com/gin-gonic/gin"
)
// ListImportsOfShow returns a list of all running and pending imports for files belonging to this show.
// @Summary List imports
// @Description Lists all running and pending imports
// @Produce json
// @Param name path string true "Name of the show"
// @Param limit query int false "Limit number of results"
// @Param offset query int false "Start listing from offset"
// @Success 200 {object} JobsListing
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/imports [get]
func (api *API) ListImportsOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -42,6 +53,19 @@ func (api *API) ListImportsOfShow(c *gin.Context) {
c.JSON(http.StatusOK, JobsListing{jobs})
}
// ReadImportOfFile retrieves import status of the file.
// @Summary Retrieve import status
// @Description Retrieves import status of the file.
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Param wait-for query string false "running|done - If given, return not before import has the given state"
// @Success 200 {object} importer.Job
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse "No job for this file"
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/import [get]
func (api *API) ReadImportOfFile(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -80,6 +104,17 @@ func (api *API) ReadImportOfFile(c *gin.Context) {
c.JSON(http.StatusOK, job)
}
// CancelImportOfFile cancels import of file.
// @Summary Cancel file import
// @Description Cancels import of file.
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 204 {object} nil
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse "No job for this file"
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/import [delete]
func (api *API) CancelImportOfFile(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......
......@@ -122,7 +122,7 @@ func (api *API) CreateShow(c *gin.Context) {
// @Description Deletes a show
// @Produce json
// @Param name path string true "Name of the show to be deleted"
// @Success 204
// @Success 204 {object} nil
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name} [delete]
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment