feat: Add api doc example with swaggo/swag

* based on 2dba85db
* build with `make api-docs`
* Swagger UI available at `/api/docs/index.html`

.gitignore

 /tank
+/tank.yaml
 /vendor/
 /cover.out
 /coverage.html
+/api/docs/swagger.*
\ No newline at end of file

Makefile

@@ -21,6 +21,11 @@ ifdef GOROOT
 GOCMD = $(GOROOT)/bin/go
 endif
 
+SWAG := swag
+ifdef GOPATH
+SWAG = $(GOPATH)/bin/swag
+endif
+
 EXECUTEABLE := tank
 
 all: build
@@ -35,6 +40,9 @@ format:
 ui:
 	$(GOCMD) generate ./ui
 
+api-docs:
+	$(SWAG) init -d api/v1/,./ -g api.go -o api/docs
+
 build: ui
 	$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
 

api/docs/docs.go

+// Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
+// This file was generated by swaggo/swag
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .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": "Lists all existing shows",
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "List shows",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ShowsListing"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/shows/{id}": {
+            "post": {
+                "description": "Creates a new show",
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "Create show",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/store.Show"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "description": "Deletes a show",
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "Delete show",
+                "responses": {
+                    "204": {
+                        "description": ""
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "api_v1.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "detail": {},
+                "error": {
+                    "type": "string"
+                }
+            }
+        },
+        "api_v1.ShowsListing": {
+            "type": "object",
+            "properties": {
+                "results": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/store.Show"
+                    }
+                }
+            }
+        },
+        "gitlab.servus.at_autoradio_tank_api_v1.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "detail": {},
+                "error": {
+                    "type": "string"
+                }
+            }
+        },
+        "gitlab.servus.at_autoradio_tank_api_v1.ShowsListing": {
+            "type": "object",
+            "properties": {
+                "results": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/store.Show"
+                    }
+                }
+            }
+        },
+        "store.Show": {
+            "type": "object",
+            "properties": {
+                "created": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "updated": {
+                    "type": "string"
+                }
+            }
+        }
+    },
+    "securityDefinitions": {
+        "ApiKeyAuth": {
+            "type": "apiKey",
+            "name": "Authorization",
+            "in": "header"
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "",
+	BasePath:         "",
+	Schemes:          []string{},
+	Title:            "AURA Tank API",
+	Description:      "Import & Playlist Daemon",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}

api/v1/api.go

@@ -28,6 +28,18 @@ 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
+
+// @license.name GPL 3
+// @license.url https://www.gnu.org/licenses/gpl
+
+// @securityDefinitions.apikey ApiKeyAuth
+// @in header
+// @name Authorization
+
 type API struct {
 	store    *store.Store
 	importer *importer.Importer

api/v1/shows.go

@@ -26,6 +26,14 @@ import (
 	"gitlab.servus.at/autoradio/tank/store"
 )
 
+// 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]
 func (api *API) ListShows(c *gin.Context) {
 	offset, limit, ok := getPaginationParameter(c)
 	if !ok {
@@ -72,6 +80,14 @@ func (api *API) ListShows(c *gin.Context) {
 	c.JSON(http.StatusOK, ShowsListing{Shows: shows})
 }
 
+// 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]
 func (api *API) CreateShow(c *gin.Context) {
 	showID := c.Param("show-id")
 	if authorized, _ := authorizeRequestForShow(c, showID); !authorized {
@@ -97,6 +113,14 @@ func (api *API) CreateShow(c *gin.Context) {
 	c.JSON(http.StatusCreated, show)
 }
 
+// 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]
 func (api *API) DeleteShow(c *gin.Context) {
 	showID := c.Param("show-id")
 	if authorized, s := authorizeRequestForShow(c, showID); !authorized {

cmd/tank/web.go

@@ -30,6 +30,9 @@ import (
 
 	"github.com/gin-gonic/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"
 	"gitlab.servus.at/autoradio/tank/auth"
 	"gitlab.servus.at/autoradio/tank/importer"
@@ -38,10 +41,11 @@ import (
 )
 
 const (
-	WebUIPathPrefix = "/ui/"
-	WebAuthPrefix   = "/auth/"
-	WebAPIv1Prefix  = "/api/v1/"
-	HealthzEndpoint = "/healthz"
+	WebUIPathPrefix  = "/ui/"
+	WebAuthPrefix    = "/auth/"
+	WebAPIDocsPrefix = "/api/docs/"
+	WebAPIv1Prefix   = "/api/v1/"
+	HealthzEndpoint  = "/healthz"
 )
 
 func apache2CombinedLogger(param gin.LogFormatterParams) string {
@@ -161,6 +165,7 @@ func runWeb(ln net.Listener, st *store.Store, im *importer.Importer, conf WebCon
 	apiV1.InstallHTTPHandler(r.Group(WebAPIv1Prefix), st, im, infoLog, errLog, dbgLog)
 	auth.InstallHTTPHandler(r.Group(WebAuthPrefix))
 	r.GET(HealthzEndpoint, func(c *gin.Context) { healthzHandler(c, st, im) })
+	r.GET(WebAPIDocsPrefix+"*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
 
 	srv := &http.Server{
 		Handler:      r,

go.mod

@@ -6,15 +6,16 @@ require (
 	github.com/codegangsta/cli v1.20.0
 	github.com/coreos/go-oidc v2.0.0+incompatible
 	github.com/coreos/go-systemd v0.0.0-20180511133405-39ca1b05acc7
-	github.com/gin-gonic/gin v1.4.0
+	github.com/gin-gonic/gin v1.7.7
 	github.com/jinzhu/gorm v1.9.8
-	github.com/kr/pretty v0.1.0 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.1 // indirect
 	github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35 // indirect
 	github.com/rs/cors v1.6.0
-	github.com/shurcooL/httpfs v0.0.0-20190707220628-8d4bc4ba7749 // indirect
-	github.com/shurcooL/vfsgen v0.0.0-20181202132449-6a9ea43bcacd // indirect
+	github.com/swaggo/gin-swagger v1.4.1
+	github.com/swaggo/swag v1.8.0
 	golang.org/x/oauth2 v0.0.0-20190319182350-c85d3e98c914
 	gopkg.in/gormigrate.v1 v1.5.0
 	gopkg.in/square/go-jose.v2 v2.3.0 // indirect
-	gopkg.in/yaml.v3 v3.0.0-20190709130402-674ba3eaed22
+	gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776
 )