Skip to content
GitLab
Commit dba4d34a authored by robwa's avatar robwa
Browse files

feat: Add API doc for files endpoints

parent cd10e239
Expand all Hide whitespace changes
Inline Side-by-side
Makefile
View file @ dba4d34a
...@@ -25,7 +25,7 @@ SWAG := swag ...@@ -25,7 +25,7 @@ SWAG := swag
ifdef GOPATH ifdef GOPATH
SWAG = $(GOPATH)/bin/swag SWAG = $(GOPATH)/bin/swag
endif endif
SWAG_ARGS := -d api/v1/,./ -g api.go SWAG_ARGS := -d api/v1/ -g api.go
EXECUTEABLE := tank EXECUTEABLE := tank
...@@ -41,9 +41,11 @@ format: ...@@ -41,9 +41,11 @@ format:
ui: ui:
$(GOCMD) generate ./ui $(GOCMD) generate ./ui
api-docs: fmt-api-docs:
$(SWAG) fmt $(SWAG_ARGS) $(SWAG) fmt $(SWAG_ARGS)
$(SWAG) init $(SWAG_ARGS) -o api/docs
api-docs:
$(SWAG) init $(SWAG_ARGS) --pd -o api/docs
build: ui build: ui
$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank $(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
......
api/docs/docs.go
View file @ dba4d34a
This diff is collapsed.
api/v1/files.go
View file @ dba4d34a
...@@ -27,6 +27,17 @@ import ( ...@@ -27,6 +27,17 @@ import (
"gitlab.servus.at/autoradio/tank/store" "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) { func (api *API) ListFilesOfShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -45,6 +56,19 @@ func (api *API) ListFilesOfShow(c *gin.Context) { ...@@ -45,6 +56,19 @@ func (api *API) ListFilesOfShow(c *gin.Context) {
c.JSON(http.StatusOK, FilesListing{files}) 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) { func (api *API) CreateFileForShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
authorized, sess := authorizeRequestForShow(c, showID) authorized, sess := authorizeRequestForShow(c, showID)
...@@ -131,6 +155,17 @@ create_file_response: ...@@ -131,6 +155,17 @@ create_file_response:
c.JSON(status, errResp) 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) { func (api *API) ReadFileOfShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -150,6 +185,19 @@ func (api *API) ReadFileOfShow(c *gin.Context) { ...@@ -150,6 +185,19 @@ func (api *API) ReadFileOfShow(c *gin.Context) {
c.JSON(http.StatusOK, file) 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) { func (api *API) PatchFileOfShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -174,6 +222,16 @@ func (api *API) PatchFileOfShow(c *gin.Context) { ...@@ -174,6 +222,16 @@ func (api *API) PatchFileOfShow(c *gin.Context) {
c.JSON(http.StatusOK, file) 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) { func (api *API) DeleteFileOfShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -195,6 +253,17 @@ func (api *API) DeleteFileOfShow(c *gin.Context) { ...@@ -195,6 +253,17 @@ func (api *API) DeleteFileOfShow(c *gin.Context) {
c.JSON(http.StatusNoContent, nil) 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) { func (api *API) ReadUsageOfFile(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -214,6 +283,17 @@ func (api *API) ReadUsageOfFile(c *gin.Context) { ...@@ -214,6 +283,17 @@ func (api *API) ReadUsageOfFile(c *gin.Context) {
c.JSON(http.StatusOK, result) 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) { func (api *API) ReadLogsOfFile(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......
api/v1/files_import.go
View file @ dba4d34a
...@@ -24,6 +24,17 @@ import ( ...@@ -24,6 +24,17 @@ import (
"github.com/gin-gonic/gin" "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) { func (api *API) ListImportsOfShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -42,6 +53,19 @@ func (api *API) ListImportsOfShow(c *gin.Context) { ...@@ -42,6 +53,19 @@ func (api *API) ListImportsOfShow(c *gin.Context) {
c.JSON(http.StatusOK, JobsListing{jobs}) 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) { func (api *API) ReadImportOfFile(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
...@@ -80,6 +104,17 @@ func (api *API) ReadImportOfFile(c *gin.Context) { ...@@ -80,6 +104,17 @@ func (api *API) ReadImportOfFile(c *gin.Context) {
c.JSON(http.StatusOK, job) 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) { func (api *API) CancelImportOfFile(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized { if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......
api/v1/shows.go
View file @ dba4d34a
...@@ -121,10 +121,10 @@ func (api *API) CreateShow(c *gin.Context) { ...@@ -121,10 +121,10 @@ func (api *API) CreateShow(c *gin.Context) {
// @Summary Delete show // @Summary Delete show
// @Description Deletes a show // @Description Deletes a show
// @Produce json // @Produce json
// @Param name path string true "Name of the show to be deleted" // @Param name path string true "Name of the show to be deleted"
// @Success 204 // @Success 204 {object} nil
// @Failure 403 {object} ErrorResponse // @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse // @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name} [delete] // @Router /api/v1/shows/{name} [delete]
func (api *API) DeleteShow(c *gin.Context) { func (api *API) DeleteShow(c *gin.Context) {
showID := c.Param("show-id") showID := c.Param("show-id")
......
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