Skip to content
GitLab
Commit fe967ec1 authored by Ernesto Rico Schmidt's avatar Ernesto Rico Schmidt
Browse files

Merge branch 'feature/7-api-docs' into 'master' 

Add api docs generated by swaggo/swag

See merge request !5
parents f7109bfc 752135a8
Pipeline #1781 passed with stages
in 20 minutes and 41 seconds
Hide whitespace changes
Inline Side-by-side
.gitignore
View file @ fe967ec1
/tank
/tank.yaml
/vendor/
/cover.out
/coverage.html
/api/docs/swagger.*
\ No newline at end of file
.gitlab-ci.yml
View file @ fe967ec1
......@@ -59,6 +59,7 @@ test-store-postgres:
build:
stage: build
script:
# we should actually use `make build` here, see #30
- go build -ldflags "-extldflags '-static'" -tags netgo -o $CI_PROJECT_DIR/tank ./cmd/tank
## sqlite needs cgo... :(
##- go build -o $CI_PROJECT_DIR/tank ./cmd/tank
......@@ -68,6 +69,28 @@ build:
paths:
- tank
build-openapi-2-scheme:
stage: build
script:
- go get -u github.com/swaggo/swag/cmd/swag
- make api-docs
artifacts:
paths:
- api/docs/swagger.yaml
build-openapi-3-scheme:
stage: build
image:
name: openapitools/openapi-generator-cli:latest-release
needs:
- job: build-openapi-2-scheme
artifacts: true
script:
- /usr/local/bin/docker-entrypoint.sh generate -i api/docs/swagger.yaml -o api/docs -g openapi-yaml --minimal-update
artifacts:
paths:
- api/docs/openapi/openapi.yaml
docker:
stage: build
image:
......
Makefile
View file @ fe967ec1
......@@ -21,6 +21,12 @@ ifdef GOROOT
GOCMD = $(GOROOT)/bin/go
endif
SWAG := swag
ifdef GOPATH
SWAG = $(GOPATH)/bin/swag
endif
SWAG_ARGS := -d api/v1/,cmd/tank/ -g api.go
EXECUTEABLE := tank
all: build
......@@ -35,6 +41,15 @@ format:
ui:
$(GOCMD) generate ./ui
fmt-api-docs:
$(SWAG) fmt $(SWAG_ARGS)
api-docs:
$(SWAG) init $(SWAG_ARGS) --pd -o api/docs
# build target actually depends on api-docs
# to allow building binary without generating api docs first, we put api/docs/docs.go under version control
# see #30
build: ui
$(GOCMD) build -o $(EXECUTEABLE) ./cmd/tank
......
api/docs/docs.go 0 → 100644
View file @ fe967ec1
// 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": {
"name": "API Support",
"url": "https://gitlab.servus.at/autoradio/tank"
},
"license": {
"name": "AGPLv3",
"url": "https://www.gnu.org/licenses/agpl-3.0"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/v1/playlists": {
"get": {
"description": "Lists all playlists.",
"produces": [
"application/json"
],
"summary": "List playlists",
"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/v1.PlaylistsListing"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/playlists/{id}": {
"get": {
"description": "Retrieves a playlist.",
"produces": [
"application/json"
],
"summary": "Retrieve playlist",
"parameters": [
{
"type": "integer",
"description": "ID of the playlist",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.Playlist"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows": {
"get": {
"description": "Lists all existing shows",
"produces": [
"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/v1.ShowsListing"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/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": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/store.Show"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"delete": {
"description": "Deletes a show",
"produces": [
"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": "No Content"
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{name}/files": {
"get": {
"description": "Lists files of show",
"produces": [
"application/json"
],
"summary": "List files",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"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/v1.FilesListing"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"post": {
"description": "Adds a file and starts import",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Add file",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"description": "URI of the file",
"name": "file",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/v1.FileCreateRequest"
}
},
{
"type": "string",
"description": "running|done - If given, return not before import has the given state",
"name": "wait-for",
"in": "query"
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/store.File"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{name}/files/{id}": {
"get": {
"description": "Retrieves file object.",
"produces": [
"application/json"
],
"summary": "Retrieve file",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.File"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"delete": {
"description": "Removes a file.",
"summary": "Delete file",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
},
"patch": {
"description": "Updates file metadata.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"summary": "Update file",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
},
{
"description": "File metadata",
"name": "metadata",
"in": "body",
"schema": {
"$ref": "#/definitions/store.FileMetadata"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/store.File"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/v1.ErrorResponse"
}
}
}
}
},
"/api/v1/shows/{name}/files/{id}/import": {
"get": {
"description": "Retrieves import status of the file.",
"produces": [
"application/json"
],
"summary": "Retrieve import status",
"parameters": [
{
"type": "string",
"description": "Name of the show",
"name": "name",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "ID of the file",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",