Commit 46725143 authored by robwa's avatar robwa
Browse files

feat: Document show endpoints

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