Skip to content
Snippets Groups Projects
Verified Commit a42e0f9b authored by Ernesto Rico Schmidt's avatar Ernesto Rico Schmidt
Browse files

docs: update API documentation annotations

parent 067d7f47
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
api/v1/files.go
+ 8
− 8
View file @ a42e0f9b
......@@ -32,7 +32,7 @@ import (
// @Summary List files
// @Description Lists files of show
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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
......@@ -169,7 +169,7 @@ create_file_response:
// @Summary Retrieve file
// @Description Retrieves file object.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Success 200 {object} store.File
// @Failure 400 {object} ErrorResponse
......@@ -211,7 +211,7 @@ func (api *API) ReadFileOfShow(c *gin.Context) {
// @Description Updates file metadata.
// @Accept json
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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
......@@ -252,7 +252,7 @@ func (api *API) PatchFileOfShow(c *gin.Context) {
//
// @Summary Delete file
// @Description Removes a file.
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Success 204
// @Failure 400 {object} ErrorResponse
......@@ -291,14 +291,14 @@ func (api *API) DeleteFileOfShow(c *gin.Context) {
// @Summary List referring playlists
// @Description Lists playlists referring to the file.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/usage/{id} [get]
// @Router /api/v1/files/{id}/usage [get]
//
// TODO: remove this together with nested routes
func (api *API) ReadUsageOfFile(c *gin.Context) {
......@@ -329,14 +329,14 @@ func (api *API) ReadUsageOfFile(c *gin.Context) {
// @Summary Retrieve import logs
// @Description Retrieves import logs of the file.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/logs/{id} [get]
// @Router /api/v1/files/{id}/logs [get]
func (api *API) ReadLogsOfFile(c *gin.Context) {
showID, err := getShowID(c)
if err != nil {
......
api/v1/files_import.go
+ 5
− 5
View file @ a42e0f9b
......@@ -29,7 +29,7 @@ import (
// @Summary List imports
// @Description Lists all running and pending imports
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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
......@@ -64,7 +64,7 @@ func (api *API) ListImportsOfShow(c *gin.Context) {
// @Summary Retrieve import status
// @Description Retrieves import status of the file.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Param waitFor query string false "running|done - If given, return not before import has the given state"
// @Success 200 {object} importer.Job
......@@ -72,7 +72,7 @@ func (api *API) ListImportsOfShow(c *gin.Context) {
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse "No job for this file"
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/import/{id} [get]
// @Router /api/v1/files/{id}/import [get]
func (api *API) ReadImportOfFile(c *gin.Context) {
showID, err := getShowID(c)
if err != nil {
......@@ -118,14 +118,14 @@ func (api *API) ReadImportOfFile(c *gin.Context) {
//
// @Summary Cancel file import
// @Description Cancels import of file.
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Success 204
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse "No job for this file"
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/import/{id} [delete]
// @Router /api/v1/files/{id}/import [delete]
func (api *API) CancelImportOfFile(c *gin.Context) {
showID, err := getShowID(c)
if err != nil {
......
api/v1/files_upload.go
+ 11
− 11
View file @ a42e0f9b
......@@ -42,14 +42,14 @@ import (
// @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 showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Success 200
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/upload/{id} [put]
// @Router /api/v1/files/{id}/upload [put]
func (api *API) UploadFileSimple(c *gin.Context) {
showID, err := getShowID(c)
if err != nil {
......@@ -385,13 +385,13 @@ func getFlowJSParameterFromQuery(r *http.Request) (id string, chunk, totalChunks
// @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 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/upload/{id} [post]
// @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/files/{id}/upload [post]
func (api *API) UploadFileFlowJS(c *gin.Context) {
id, err := idFromString(c.Param("file-id"))
if err != nil {
......@@ -466,7 +466,7 @@ func (api *API) UploadFileFlowJS(c *gin.Context) {
//
// @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 showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the file"
// @Param flowIdentifier query string true "A unique identifier for the uploaded file"
//
......@@ -478,7 +478,7 @@ func (api *API) UploadFileFlowJS(c *gin.Context) {
// @Failure 403 {object} ErrorResponse
// @Failure 409 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/upload/{id} [get]
// @Router /api/v1/files/{id}/upload [get]
func (api *API) TestFileFlowJS(c *gin.Context) {
showID, err := getShowID(c)
if err != nil {
......
api/v1/playlists.go
+ 11
− 14
View file @ a42e0f9b
......@@ -30,7 +30,7 @@ import (
// @Summary List playlists
// @Description Lists playlists of show.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID 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
......@@ -98,7 +98,7 @@ func (api *API) CreatePlaylistForShow(c *gin.Context) {
// @Summary Retrieve playlist
// @Description Retrieves a playlist of a show.
// @Produce json
// @Param showID query int true "ID of the show"
// @Param showId query int true "ID of the show"
// @Param id path int true "ID of the playlist"
// @Success 200 {object} store.Playlist
// @Failure 400 {object} ErrorResponse
......@@ -137,7 +137,6 @@ func (api *API) ReadPlaylistOfShow(c *gin.Context) {
// @Description Updates a playlist of a show.
// @Accept json
// @Produce json
// @Param showID query int true "ID of the show"
// @Param id path int true "ID of the playlist"
// @Param playlist body store.Playlist true "Playlist data"
// @Success 200 {object} store.Playlist
......@@ -175,8 +174,7 @@ func (api *API) UpdatePlaylistOfShow(c *gin.Context) {
//
// @Summary Delete playlist
// @Description Deletes a playlist of a show.
// @Param showID query int true "ID of the show"
// @Param id path int true "ID of the playlist"
// @Param id path int true "ID of the playlist"
// @Success 204
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
......@@ -215,8 +213,8 @@ func (api *API) DeletePlaylistOfShow(c *gin.Context) {
// @Summary List playlists
// @Description Lists all playlists, the ones of a show or the ones that include a file
// @Produce json
// @Param showID query int false "ID of the show"
// @Param fileId query int false "ID of the file"
// @Param showId query int false "ID of the show"
// @Param fileId query int false "ID of the file"
// @Param limit query int false "Limit number of results"
// @Param offset query int false "Start listing from offset"
// @Success 200 {object} PlaylistsListing
......@@ -278,13 +276,12 @@ func (api *API) ListPlaylists(c *gin.Context) {
// @Summary Retrieve playlist
// @Description Retrieves a playlist.
// @Produce json
// @Param showID query int false "ID of the show"
// @Param id path int true "ID of the playlist"
// @Success 200 {object} store.Playlist
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Param id path int true "ID of the playlist"
// @Success 200 {object} store.Playlist
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 404 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/playlists/{id} [get]
func (api *API) ReadPlaylist(c *gin.Context) {
if authorized, _ := authorizeRequestAllShows(c); !authorized {
......
api/v1/shows.go
+ 1
− 1
View file @ a42e0f9b
......@@ -89,7 +89,7 @@ func (api *API) ListShows(c *gin.Context) {
// @Summary Create show
// @Description Creates a new show
// @Produce json
// @Param showID query int true "ID of the show to be created"
// @Param showId query int true "ID of the show to be created"
// @Param cloneFrom query int false "If given, all files and playlists will be copied from the show"
// @Success 201 {object} store.Show
// @Failure 403 {object} ErrorResponse
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment