add swagger support

- install swaggo
- add swagger config option

.github/workflows/golangci-lint.yml

@@ -31,6 +31,13 @@ jobs:
         run: |
           make -s version | tr -d '\n' > VERSION
         shell: sh
+
+      - name: Install and initialize swagger
+        run: |
+          go install github.com/swaggo/swag/cmd/swag@latest
+          swag init
+        shell: sh
+
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v4
         with:

.gitignore

@@ -68,3 +68,4 @@ debian/aptly-dbg.debhelper.log
 debian/aptly-dbg.substvars
 debian/aptly-dbg/
 
+docs/

Makefile

@@ -17,10 +17,16 @@ RELEASE=no
 help:  ## Print this help
 	@grep -E '^[a-zA-Z][a-zA-Z0-9_-]*:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-all: prepare test bench check system-test
+all: prepare test bench check system-test  # used for system tests in ci
 
 prepare:  ## Install go module dependencies
+	# set version
+	@make version > VERSION
+	# download modules
 	go mod download
+	# install and initialize swagger
+	go install github.com/swaggo/swag/cmd/swag@latest
+	PATH=$(BINPATH)/:$(PATH) swag init
 	go mod verify
 	go mod tidy -v
 	go generate
@@ -46,8 +52,10 @@ endif
 system-test: install system/env  ## Run system tests in github CI
 ifeq ($(RUN_LONG_TESTS), yes)
 	go generate
+	# install etcd
 	test -d /srv/etcd || system/t13_etcd/install-etcd.sh
 	system/t13_etcd/start-etcd.sh &
+	# build coverage binary
 	go test -v -coverpkg="./..." -c -tags testruncli
 	kill `cat /tmp/etcd.pid`
 
@@ -61,6 +69,10 @@ docker-test: ## Run system tests
 	@echo Building aptly.test ...
 	@rm -f aptly.test
 	go generate
+	# install and initialize swagger
+	go install github.com/swaggo/swag/cmd/swag@latest
+	PATH=$(BINPATH)/:$(PATH) swag init
+	# build coverage binary
 	go test -v -coverpkg="./..." -c -tags testruncli
 	@echo Running python tests ...
 	@test -e aws.creds && . ./aws.creds; \
@@ -112,32 +124,50 @@ releasetype:  # Print release type (ci/release)
 	echo $$reltype
 
 build:  ## Build aptly
+	# install and initialize swagger
+	unset GOBIN; go install github.com/swaggo/swag/cmd/swag@latest
+	PATH=$(BINPATH)/:$(PATH) swag init
+	# prepare
 	go mod tidy
 	go generate
+	# build
 	go build -o build/aptly
 
 dpkg:  ## Build debian packages
 	@test -n "$(DEBARCH)" || (echo "please define DEBARCH"; exit 1)
+	# go generate
 	GOPATH=$$PWD/.go go generate -v
+	# install and initialize swagger
+	go install github.com/swaggo/swag/cmd/swag@latest
+	PATH=$(BINPATH)/:$(PATH) swag init
+	# set debian version
 	@if [ "`make -s releasetype`" = "ci" ]; then  \
 		echo CI Build, setting version... ; \
 		cp debian/changelog debian/changelog.dpkg-bak ; \
 		DEBEMAIL="CI <ci@aptly>" dch -v `make -s version` "CI build" ; \
 	fi
+	# Run dpkg-buildpackage
 	buildtype="any" ; \
 	if [ "$(DEBARCH)" = "amd64" ]; then  \
 	  buildtype="any,all" ; \
 	fi ; \
 	echo Building: $$buildtype ; \
 	dpkg-buildpackage -us -uc --build=$$buildtype -d --host-arch=$(DEBARCH)
+	# cleanup
 	@test -f debian/changelog.dpkg-bak && mv debian/changelog.dpkg-bak debian/changelog || true ; \
 	mkdir -p build && mv ../*.deb build/ ; \
 	cd build && ls -l *.deb
 
 binaries:  ## Build binary releases (FreeBSD, MacOS, Linux tar)
-	@mkdir -p build/tmp/man build/tmp/completion/bash_completion.d build/tmp/completion/zsh/vendor-completions
+	# set version
 	@make version > VERSION
+	# install and initialize swagger
+	GOOS=linux GOARCH=amd64 go install github.com/swaggo/swag/cmd/swag@latest
+	PATH=$(BINPATH)/:$(PATH) swag init
+	# build aptly
 	GOOS=$(GOOS) GOARCH=$(GOARCH) go build -o build/tmp/aptly -ldflags='-extldflags=-static'
+	# install
+	@mkdir -p build/tmp/man build/tmp/completion/bash_completion.d build/tmp/completion/zsh/vendor-completions
 	@cp man/aptly.1 build/tmp/man/
 	@cp completion.d/aptly build/tmp/completion/bash_completion.d/
 	@cp completion.d/_aptly build/tmp/completion/zsh/vendor-completions/

api/error.go

@@ -0,0 +1,5 @@
+package api
+
+type Error struct {
+	Error string `json:"error"`
+}

api/router.go

@@ -11,6 +11,10 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 	"github.com/rs/zerolog/log"
+
+	_ "github.com/aptly-dev/aptly/docs" // import docs
+	swaggerFiles "github.com/swaggo/files"
+	ginSwagger "github.com/swaggo/gin-swagger"
 )
 
 var context *ctx.AptlyContext
@@ -22,7 +26,27 @@ func apiMetricsGet() gin.HandlerFunc {
 	}
 }
 
+func redirectSwagger(c *gin.Context) {
+	if c.Request.URL.Path == "/docs/" {
+		c.Redirect(http.StatusMovedPermanently, "/docs/index.html")
+		return
+	}
+	c.Next()
+}
+
 // Router returns prebuilt with routes http.Handler
+// @title           Aptly API
+// @version         1.0
+// @description     Aptly REST API Documentation
+
+// @contact.name   Aptly
+// @contact.url    http://github.com/aptly-dev/aptly
+// @contact.email  support@aptly.info
+
+// @license.name  MIT License
+// @license.url   http://www.
+
+// @BasePath  /api
 func Router(c *ctx.AptlyContext) http.Handler {
 	if aptly.EnableDebug {
 		gin.SetMode(gin.DebugMode)
@@ -48,6 +72,12 @@ func Router(c *ctx.AptlyContext) http.Handler {
 
 	router.Use(gin.Recovery(), gin.ErrorLogger())
 
+	if c.Config().EnableSwaggerEndpoint {
+		router.Use(redirectSwagger)
+		url := ginSwagger.URL("/docs/doc.json")
+		router.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
+	}
+
 	if c.Config().EnableMetricsEndpoint {
 		MetricsCollectorRegistrar.Register(router)
 	}

debian/aptly.conf

@@ -33,5 +33,6 @@
     "type": "",
     "url": "",
     "dbPath": ""
-  }
+  },
+  "enableSwaggerEndpoint": false
 }

system/run-system-tests

@@ -7,4 +7,4 @@ rm -rf /tmp/aptly*
 usermod -u `stat -c %u /app` aptly >/dev/null
 chown -R `stat -c %u /app` /var/lib/aptly
 
-su - aptly -c "cd /app; export GOPATH=/app/.go; go mod tidy; make docker-test TEST=$@"
+su - aptly -c "cd /app; export GOPATH=/app/.go; make docker-test TEST=$@"

system/t02_config/ConfigShowTest_gold

@@ -34,5 +34,6 @@
         "type": "",
         "url": "",
         "dbPath": ""
-    }
+    },
+    "enableSwaggerEndpoint": false
 }

system/t02_config/CreateConfigTest_gold

@@ -34,5 +34,6 @@
     "type": "",
     "url": "",
     "dbPath": ""
-  }
+  },
+  "enableSwaggerEndpoint": false
 }

utils/config.go

@@ -42,6 +42,7 @@ type ConfigStructure struct { // nolint: maligned
 	LogFormat              string                           `json:"logFormat"`
 	ServeInAPIMode         bool                             `json:"serveInAPIMode"`
 	DatabaseBackend        DBConfig                         `json:"databaseBackend"`
+	EnableSwaggerEndpoint  bool                             `json:"enableSwaggerEndpoint"`
 }
 
 // DBConfig
@@ -180,6 +181,7 @@ var Config = ConfigStructure{
 	LogLevel:               "debug",
 	LogFormat:              "default",
 	ServeInAPIMode:         false,
+	EnableSwaggerEndpoint:  false,
 }
 
 // LoadConfig loads configuration from json file

utils/config_test.go

@@ -148,7 +148,8 @@ func (s *ConfigSuite) TestSaveConfig(c *C) {
 		"    \"type\": \"\",\n"+
 		"    \"url\": \"\",\n"+
                 "    \"dbPath\": \"\"\n" +
-		"  }\n"+
+		"  },\n"+
+                "  \"enableSwaggerEndpoint\": false\n" +
 		"}")
 }