Skip to content
GitLab
Commit 2dba85db authored by Christian Pointner's avatar Christian Pointner
Browse files

api docs: add experimential swagger-docs

parent 220aadb2
Pipeline #605 passed with stages
in 4 minutes and 14 seconds
Hide whitespace changes
Inline Side-by-side
Makefile
View file @ 2dba85db
...@@ -27,6 +27,12 @@ ifdef GOROOT ...@@ -27,6 +27,12 @@ ifdef GOROOT
GOCMD = $(GOROOT)/bin/go GOCMD = $(GOROOT)/bin/go
endif endif
SWAG := swag
ifdef GOPATH
SWAG = $(GOPATH)/bin/swag
endif
EXECUTEABLE := tank EXECUTEABLE := tank
all: build all: build
...@@ -41,6 +47,9 @@ format: ...@@ -41,6 +47,9 @@ format:
ui: ui:
$(GOCMD) generate ./ui $(GOCMD) generate ./ui
api-docs:
$(SWAG) init -g api/v1/api.go -o api/docs
build: ui build: ui
$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank $(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
......
api/docs/docs.go 0 → 100644
View file @ 2dba85db
// GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
// This file was generated by swaggo/swag at
// 2020-03-19 00:14:30.681690436 +0100 CET m=+0.110256741
package docs
import (
"bytes"
"encoding/json"
"strings"
"github.com/alecthomas/template"
"github.com/swaggo/swag"
)
var doc = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{.Description}}",
"title": "{{.Title}}",
"contact": {
"url": "https://gitlab.servus.at/autoradio/tank"
},
"license": {
"name": "GPL 3",
"url": "https://www.gnu.org/licenses/gpl"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/v1/shows": {
"get": {
"description": "list all existing shows",
"produces": [
"application/json"
],
"summary": "List shows",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/v1.ShowsListing"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{id}": {
"post": {
"description": "create a new show",
"produces": [
"application/json"
],
"summary": "create show",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Show"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"delete": {
"description": "create a new show",
"produces": [
"application/json"
],
"summary": "delete show",
"responses": {
"204": {},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"store.Show": {
"type": "object",
"properties": {
"created": {
"type": "string"
},
"name": {
"type": "string"
},
"updated": {
"type": "string"
}
}
},
"v1.ErrorResponse": {
"type": "object",
"properties": {
"detail": {
"type": "object"
},
"error": {
"type": "string"
}
}
},
"v1.ShowsListing": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/store.Show"
}
}
}
}
},
"securityDefinitions": {
"ApiKeyAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}`
type swaggerInfo struct {
Version string
Host string
BasePath string
Schemes []string
Title string
Description string
}
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = swaggerInfo{
Version: "1.0",
Host: "",
BasePath: "",
Schemes: []string{},
Title: "AURA Tank API",
Description: "Import & Playlist Daemon",
}
type s struct{}
func (s *s) ReadDoc() string {
sInfo := SwaggerInfo
sInfo.Description = strings.Replace(sInfo.Description, "\n", "\\n", -1)
t, err := template.New("swagger_info").Funcs(template.FuncMap{
"marshal": func(v interface{}) string {
a, _ := json.Marshal(v)
return string(a)
},
}).Parse(doc)
if err != nil {
return doc
}
var tpl bytes.Buffer
if err := t.Execute(&tpl, sInfo); err != nil {
return doc
}
return tpl.String()
}
func init() {
swag.Register(swag.Name, &s{})
}
api/docs/swagger.json 0 → 100644
View file @ 2dba85db
{
"swagger": "2.0",
"info": {
"description": "Import \u0026 Playlist Daemon",
"title": "AURA Tank API",
"contact": {
"url": "https://gitlab.servus.at/autoradio/tank"
},
"license": {
"name": "GPL 3",
"url": "https://www.gnu.org/licenses/gpl"
},
"version": "1.0"
},
"paths": {
"/api/v1/shows": {
"get": {
"description": "list all existing shows",
"produces": [
"application/json"
],
"summary": "List shows",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/v1.ShowsListing"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{id}": {
"post": {
"description": "create a new show",
"produces": [
"application/json"
],
"summary": "create show",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Show"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"delete": {
"description": "create a new show",
"produces": [
"application/json"
],
"summary": "delete show",
"responses": {
"204": {},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"store.Show": {
"type": "object",
"properties": {
"created": {
"type": "string"
},
"name": {
"type": "string"
},
"updated": {
"type": "string"
}
}
},
"v1.ErrorResponse": {
"type": "object",
"properties": {
"detail": {
"type": "object"
},
"error": {
"type": "string"
}
}
},
"v1.ShowsListing": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/store.Show"
}
}
}
}
},
"securityDefinitions": {
"ApiKeyAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}
\ No newline at end of file
api/docs/swagger.yaml 0 → 100644
View file @ 2dba85db
definitions:
store.Show:
properties:
created:
type: string
name:
type: string
updated:
type: string
type: object
v1.ErrorResponse:
properties:
detail:
type: object
error:
type: string
type: object
v1.ShowsListing:
properties:
results:
items:
$ref: '#/definitions/store.Show'
type: array
type: object
info:
contact:
url: https://gitlab.servus.at/autoradio/tank
description: Import & Playlist Daemon
license:
name: GPL 3
url: https://www.gnu.org/licenses/gpl
title: AURA Tank API
version: "1.0"
paths:
/api/v1/shows:
get:
description: list all existing shows
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/v1.ShowsListing'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/v1.ErrorResponse'
summary: List shows
/api/v1/shows/{id}:
delete:
description: create a new show
produces:
- application/json
responses:
"204": {}
"403":
description: Forbidden
schema:
$ref: '#/definitions/v1.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/v1.ErrorResponse'
summary: delete show
post:
description: create a new show
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/store.Show'
"403":
description: Forbidden
schema:
$ref: '#/definitions/v1.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/v1.ErrorResponse'
summary: create show
securityDefinitions:
ApiKeyAuth:
in: header
name: Authorization
type: apiKey
swagger: "2.0"
api/v1/api.go
View file @ 2dba85db
...@@ -34,6 +34,18 @@ import ( ...@@ -34,6 +34,18 @@ import (
"gitlab.servus.at/autoradio/tank/store" "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
// @license.name GPL 3
// @license.url https://www.gnu.org/licenses/gpl
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
type API struct { type API struct {
store *store.Store store *store.Store
importer *importer.Importer importer *importer.Importer
......
api/v1/shows.go
View file @ 2dba85db
...@@ -32,6 +32,14 @@ import ( ...@@ -32,6 +32,14 @@ import (
"gitlab.servus.at/autoradio/tank/store" "gitlab.servus.at/autoradio/tank/store"
) )
// ListShows returns a list of all shows that are accessable to the current session.
// If authentication is disabled a least of all exisiting shows is returned.
// @Summary List shows
// @Description list all existing shows
// @Produce json
// @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 {
...@@ -78,6 +86,14 @@ func (api *API) ListShows(c *gin.Context) { ...@@ -78,6 +86,14 @@ func (api *API) ListShows(c *gin.Context) {
c.JSON(http.StatusOK, ShowsListing{Shows: shows}) c.JSON(http.StatusOK, ShowsListing{Shows: shows})
} }
// CreateShow creates a new show (as a clone from another show...)
// @Summary create show
// @Description create a new show
// @Produce json
// @Success 200 {object} store.Show
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{id} [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 {
...@@ -103,6 +119,14 @@ func (api *API) CreateShow(c *gin.Context) { ...@@ -103,6 +119,14 @@ func (api *API) CreateShow(c *gin.Context) {
c.JSON(http.StatusCreated, show) c.JSON(http.StatusCreated, show)
} }
// DeleteShow deletes a new show
// @Summary delete show
// @Description create a new show
// @Produce json
// @Success 204
// @Failure 403 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/shows/{id} [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 {
......
cmd/tank/web.go
View file @ 2dba85db
...@@ -36,6 +36,9 @@ import ( ...@@ -36,6 +36,9 @@ import (
"github.com/gin-gonic/gin" "github.com/gin-gonic/gin"
cors "github.com/rs/cors/wrapper/gin" cors "github.com/rs/cors/wrapper/gin"
"github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
_ "gitlab.servus.at/autoradio/tank/api/docs"
apiV1 "gitlab.servus.at/autoradio/tank/api/v1" apiV1 "gitlab.servus.at/autoradio/tank/api/v1"
"gitlab.servus.at/autoradio/tank/auth" "gitlab.servus.at/autoradio/tank/auth"
"gitlab.servus.at/autoradio/tank/importer" "gitlab.servus.at/autoradio/tank/importer"
...@@ -44,10 +47,11 @@ import ( ...@@ -44,10 +47,11 @@ import (
) )
const ( const (
WebUIPathPrefix = "/ui/" WebUIPathPrefix = "/ui/"
WebAuthPrefix = "/auth/" WebAuthPrefix = "/auth/"
WebAPIv1Prefix = "/api/v1/" WebAPIDocsPrefix = "/api/docs/"
HealthzEndpoint = "/healthz" WebAPIv1Prefix = "/api/v1/"
HealthzEndpoint = "/healthz"
) )
func apache2CombinedLogger(param gin.LogFormatterParams) string { func apache2CombinedLogger(param gin.LogFormatterParams) string {
...@@ -164,6 +168,8 @@ func runWeb(ln net.Listener, st *store.Store, im *importer.Importer, conf WebCon ...@@ -164,6 +168,8 @@ func runWeb(ln net.Listener, st *store.Store, im *importer.Importer, conf WebCon
r.StaticFS(WebUIPathPrefix, ui.Assets) r.StaticFS(WebUIPathPrefix, ui.Assets)
} }
r.GET(WebAPIDocsPrefix+"*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
apiV1.InstallHTTPHandler(r.Group(WebAPIv1Prefix), st, im, infoLog, errLog, dbgLog) apiV1.InstallHTTPHandler(r.Group(WebAPIv1Prefix), st, im, infoLog, errLog, dbgLog)
auth.InstallHTTPHandler(r.Group(WebAuthPrefix)) auth.InstallHTTPHandler(r.Group(WebAuthPrefix))
r.GET(HealthzEndpoint, func(c *gin.Context) { healthzHandler(c, st, im) }) r.GET(HealthzEndpoint, func(c *gin.Context) { healthzHandler(c, st, im) })
......
go.mod
View file @ 2dba85db
...@@ -3,16 +3,18 @@ module gitlab.servus.at/autoradio/tank ...@@ -3,16 +3,18 @@ module gitlab.servus.at/autoradio/tank
go 1.12 go 1.12
require ( require (
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
github.com/codegangsta/cli v1.20.0 github.com/codegangsta/cli v1.20.0
github.com/coreos/go-oidc v2.0.0+incompatible github.com/coreos/go-oidc v2.0.0+incompatible
github.com/coreos/go-systemd v0.0.0-20180511133405-39ca1b05acc7 github.com/coreos/go-systemd v0.0.0-20180511133405-39ca1b05acc7
github.com/gin-gonic/gin v1.4.0 github.com/gin-gonic/gin v1.4.0
github.com/jinzhu/gorm v1.9.8 github.com/jinzhu/gorm v1.9.8
github.com/kr/pretty v0.1.0 // indirect
github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35 // indirect github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35 // indirect
github.com/rs/cors v1.6.0 github.com/rs/cors v1.6.0
github.com/shurcooL/httpfs v0.0.0-20190707220628-8d4bc4ba7749 // indirect github.com/shurcooL/httpfs v0.0.0-20190707220628-8d4bc4ba7749 // indirect
github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd // indirect github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd // indirect
github.com/swaggo/gin-swagger v1.2.0
github.com/swaggo/swag v1.6.5
golang.org/x/oauth2 v0.0.0-20190319182350-c85d3e98c914 golang.org/x/oauth2 v0.0.0-20190319182350-c85d3e98c914
gopkg.in/gormigrate.v1 v1.5.0 gopkg.in/gormigrate.v1 v1.5.0
gopkg.in/square/go-jose.v2 v2.3.0 // indirect gopkg.in/square/go-jose.v2 v2.3.0 // indirect
......