Skip to content

GitLab

Commit 46725143 authored by robwa's avatar robwa
Browse files

feat: Document show endpoints

parent 308fe1fd
Hide whitespace changes
Inline Side-by-side
Makefile
View file @ 46725143
......@@ -25,6 +25,7 @@ SWAG := swag
ifdef GOPATH
SWAG = $(GOPATH)/bin/swag
endif
SWAG_ARGS := -d api/v1/,./ -g api.go
EXECUTEABLE := tank
......@@ -41,7 +42,8 @@ ui:
$(GOCMD) generate ./ui
api-docs:
$(SWAG) init -d api/v1/,./ -g api.go -o api/docs
$(SWAG) fmt $(SWAG_ARGS)
$(SWAG) init $(SWAG_ARGS) -o api/docs
build: ui
$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
......
api/docs/docs.go
View file @ 46725143
......@@ -11,11 +11,12 @@ const docTemplate = `{
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {
"name": "API Support",
"url": "https://gitlab.servus.at/autoradio/tank"
},
"license": {
"name": "GPL 3",
"url": "https://www.gnu.org/licenses/gpl"
"name": "AGPLv3",
"url": "https://www.gnu.org/licenses/agpl-3.0"
},
"version": "{{.Version}}"
},
......@@ -29,29 +30,58 @@ const docTemplate = `{
"application/json"
],
"summary": "List shows",
"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/gitlab.servus.at_autoradio_tank_api_v1.ShowsListing"
"$ref": "#/definitions/api_v1.ShowsListing"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
"$ref": "#/definitions/api_v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{id}": {
"/api/v1/shows/{name}": {
"post": {
"description": "Creates a new show",
"produces": [
"application/json"
],
"summary": "Create show",
"parameters": [
{
"type": "string",
"description": "Name of the show to be created",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "If given, all files and playlists will be copied from the show",
"name": "clone-from",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
......@@ -62,13 +92,13 @@ const docTemplate = `{
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
"$ref": "#/definitions/api_v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
"$ref": "#/definitions/api_v1.ErrorResponse"
}
}
}
......@@ -79,6 +109,15 @@ const docTemplate = `{
"application/json"
],
"summary": "Delete show",
"parameters": [
{
"type": "string",
"description": "Name of the show to be deleted",
"name": "name",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": ""
......@@ -86,13 +125,13 @@ const docTemplate = `{
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
"$ref": "#/definitions/api_v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
"$ref": "#/definitions/api_v1.ErrorResponse"
}
}
}
......
api/v1/api.go
View file @ 46725143
//
// tank, Import and Playlist Daemon for Aura project
// Copyright (C) 2017-2020 Christian Pointner <equinox@helsinki.at>
// Copyright (C) 2017-2020 Christian Pointner <equinox@helsinki.at>
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
......@@ -28,17 +28,19 @@ import (
"gitlab.servus.at/autoradio/tank/store"
)
// @title AURA Tank API
// @version 1.0
// @description Import & Playlist Daemon
// @contact.url https://gitlab.servus.at/autoradio/tank
// @title AURA Tank API
// @version 1.0
// @description Import & Playlist Daemon
// @license.name GPL 3
// @license.url https://www.gnu.org/licenses/gpl
// @contact.name API Support
// @contact.url https://gitlab.servus.at/autoradio/tank
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
// @license.name AGPLv3
// @license.url https://www.gnu.org/licenses/agpl-3.0
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
type API struct {
store *store.Store
......
api/v1/shows.go
View file @ 46725143
......@@ -27,13 +27,15 @@ import (
)
// ListShows returns a list of all shows that are accessible to the current session.
// If authentication is disabled a least of all existing shows is returned.
// @Summary List shows
// @Description Lists all existing shows
// @Produce json
// @Success 200 {object} ShowsListing
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows [get]
// If authentication is disabled a list of all existing shows is returned.
// @Summary List shows
// @Description Lists all existing shows
// @Produce json
// @Param limit query int false "Limit number of results"
// @Param offset query int false "Start listing from offset"
// @Success 200 {object} ShowsListing
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows [get]
func (api *API) ListShows(c *gin.Context) {
offset, limit, ok := getPaginationParameter(c)
if !ok {
......@@ -81,13 +83,15 @@ func (api *API) ListShows(c *gin.Context) {
}
// CreateShow creates a new show.
// @Summary Create show
// @Description Creates a new show
// @Produce json
// @Success 200 {object} store.Show
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{id} [post]
// @Summary Create show
// @Description Creates a new show
// @Produce json
// @Param name path string true "Name of the show to be created"
// @Param clone-from query string false "If given, all files and playlists will be copied from the show"
// @Success 200 {object} store.Show
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name} [post]
func (api *API) CreateShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
......@@ -114,13 +118,14 @@ func (api *API) CreateShow(c *gin.Context) {
}
// DeleteShow deletes a show.
// @Summary Delete show
// @Description Deletes a show
// @Produce json
// @Success 204
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{id} [delete]
// @Summary Delete show
// @Description Deletes a show
// @Produce json
// @Param name path string true "Name of the show to be deleted"
// @Success 204
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{name} [delete]
func (api *API) DeleteShow(c *gin.Context) {
showID := c.Param("show-id")
if authorized, s := authorizeRequestForShow(c, showID); !authorized {
......
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