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

feat: Add API doc for uploads and playlists

parent dba4d34a
Hide whitespace changes
Inline Side-by-side
api/docs/docs.go
View file @ b1141910
......@@ -23,6 +23,93 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/v1/playlists": {
"get": {
"description": "Lists all playlists.",
"produces": [
"application/json"
],
"summary": "List playlists",
"parameters": [
{
"type": "integer",
"description": "Limit number of results",
"name": "limit",
"in": "query"
},
{
"type": "integer",
"description": "Start listing from offset",
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/v1.PlaylistsListing"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/playlists/{id}": {
"get": {
"description": "Retrieves a playlist.",
"produces": [
"application/json"
],
"summary": "Retrieve playlist",
"parameters": [
{
"type": "integer",
"description": "ID of the playlist",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Playlist"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows": {
"get": {
"description": "Lists all existing shows",
......@@ -564,6 +651,168 @@ const docTemplate = `{
}
}
},
"/api/v1/shows/{name}/files/{id}/upload": {
"get": {
"description": "Uploads file content. Only available if file was created using SourceURI set to upload://-type and file import state is running.",
"summary": "Upload file content",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "A unique identifier for the uploaded file",
"name": "flowIdentifier",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"put": {
"description": "Uploads file content. Only available if file was created using SourceURI set to upload://-type and file import state is running.",
"consumes": [
"application/octet-stream"
],
"produces": [
"application/json"
],
"summary": "Upload file content",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": ""
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"post": {
"description": "Uploads file content via flow.js. Only available if file was created using SourceURI set to upload://-type and file import state is running.",
"consumes": [
"multipart/form-data"
],
"summary": "Upload file content",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{name}/files/{id}/usage": {
"get": {
"description": "Lists playlists referring to the file.",
......@@ -664,6 +913,265 @@ const docTemplate = `{
}
}
}
},
"/api/v1/shows/{name}/playlists": {
"get": {
"description": "Lists playlists of show.",
"produces": [
"application/json"
],
"summary": "List playlists",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Limit number of results",
"name": "limit",
"in": "query"
},
{
"type": "integer",
"description": "Start listing from offset",
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/v1.PlaylistsListing"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"post": {
"description": "Creates a new playlist for the show.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Create playlist",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"description": "Playlist data",
"name": "playlist",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/store.Playlist"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/store.Playlist"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{name}/playlists/{id}": {
"get": {
"description": "Retrieves a playlist of a show.",
"produces": [
"application/json"
],
"summary": "Retrieve playlist",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the playlist",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Playlist"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"put": {
"description": "Updates a playlist of a show.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Update playlist",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the playlist",
"name": "id",
"in": "path",
"required": true
},
{
"description": "Playlist data",
"name": "playlist",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/store.Playlist"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Playlist"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"delete": {
"description": "Deletes a playlist of a show.",
"summary": "Delete playlist",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the playlist",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
}
},
"definitions": {
......@@ -950,6 +1458,17 @@ const docTemplate = `{
}
}
},
"v1.PlaylistsListing": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/store.Playlist"
}
}
}
},
"v1.ShowsListing": {
"type": "object",
"properties": {
......
api/v1/files_upload.go
View file @ b1141910
......@@ -37,6 +37,18 @@ import (
//******* simple binary http upload
// UploadFileSimple uploads file content.
// @Summary Upload file content
// @Description Uploads file content. Only available if file was created using SourceURI set to upload://-type and file import state is running.
// @Accept octet-stream
// @Produce json
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 200
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/upload [put]
func (api *API) UploadFileSimple(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -364,6 +376,18 @@ func getFlowJSParameterFromQuery(r *http.Request) (id string, chunk, totalChunks
return
}
// UploadFileFlowJS uploads file content via flow.js.
// @Summary Upload file content
// @Description Uploads file content via flow.js. Only available if file was created using SourceURI set to upload://-type and file import state is running.
// @Accept mpfd
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Success 200 {object} nil
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 409 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/upload [post]
func (api *API) UploadFileFlowJS(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -429,6 +453,20 @@ func (api *API) UploadFileFlowJS(c *gin.Context) {
c.JSON(http.StatusOK, nil)
}
// TestFileFlowJS uploads file content.
// @Summary Upload file content
// @Description Uploads file content. Only available if file was created using SourceURI set to upload://-type and file import state is running.
// @Param name path string true "Name of the show"
// @Param id path int true "ID of the file"
// @Param flowIdentifier query string true "A unique identifier for the uploaded file"
// TODO: document all flow.js params
// @Success 200 {object} nil
// @Success 204 {object} nil
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 409 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/files/{id}/upload [get]
func (api *API) TestFileFlowJS(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......
api/v1/playlists.go
View file @ b1141910
......@@ -26,6 +26,17 @@ import (
"gitlab.servus.at/autoradio/tank/store"
)
// ListPlaylistsOfShow lists playlists.
// @Summary List playlists
// @Description Lists playlists 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} PlaylistsListing
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/playlists [get]
func (api *API) ListPlaylistsOfShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -44,6 +55,18 @@ func (api *API) ListPlaylistsOfShow(c *gin.Context) {
c.JSON(http.StatusOK, PlaylistsListing{playlists})
}
// CreatePlaylistForShow creates a new playlist.
// @Summary Create playlist
// @Description Creates a new playlist for the show.
// @Accept json
// @Produce json
// @Param name path string true "Name of the show"
// @Param playlist body store.Playlist true "Playlist data"
// @Success 201 {object} store.Playlist
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name}/playlists [post]
func (api *API) CreatePlaylistForShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -63,6 +86,17 @@ func (api *API) CreatePlaylistForShow(c *gin.Context) {
c.JSON(http.StatusCreated, playlist)
}
// ReadPlaylistOfShow retrieves a playlist of a show.
// @Summary Retrieve playlist
// @Description Retrieves a playlist of a show.