swagger: add api doc

api/files.go

@@ -33,7 +33,12 @@ func verifyDir(c *gin.Context) bool {
 	return true
 }
 
-// GET /files
+// @Summary Get files
+// @Description Get list of uploaded files.
+// @Tags Files
+// @Produce  json
+// @Success 200 {array} string "List of files"
+// @Router /api/files [get]
 func apiFilesListDirs(c *gin.Context) {
 	list := []string{}
 	listLock := &sync.Mutex{}

api/packages.go

@@ -16,7 +16,15 @@ func apiPackagesShow(c *gin.Context) {
 	c.JSON(200, p)
 }
 
-// GET /api/packages
+// @Summary Get packages
+// @Description Get list of packages.
+// @Tags Packages
+// @Consume  json
+// @Produce  json
+// @Param q query string false "search query"
+// @Param format query string false "format: `details` for more detailed information"
+// @Success 200 {array} string "List of packages"
+// @Router /api/packages [get]
 func apiPackages(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
 	collection := collectionFactory.PackageCollection()

api/publish.go

@@ -53,7 +53,12 @@ func parseEscapedPath(path string) string {
 	return result
 }
 
-// GET /publish
+// @Summary Get publish points
+// @Description Get list of available publish points. Each publish point is returned as in “show” API.
+// @Tags Publish
+// @Produce  json
+// @Success 200 {array} deb.PublishedRepo
+// @Router /api/publish [get]
 func apiPublishList(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
 	collection := collectionFactory.PublishedRepoCollection()

api/repos.go

@@ -50,7 +50,12 @@ func reposServeInAPIMode(c *gin.Context) {
 	c.FileFromFS(pkgpath, http.Dir(publicPath))
 }
 
-// GET /api/repos
+// @Summary Get repos
+// @Description Get list of available repos. Each repo is returned as in “show” API.
+// @Tags Repos
+// @Produce  json
+// @Success 200 {array} deb.LocalRepo
+// @Router /api/repos [get]
 func apiReposList(c *gin.Context) {
 	result := []*deb.LocalRepo{}
 

api/s3.go

@@ -4,7 +4,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// GET /api/s3
+// @Summary Get S3 buckets
+// @Description Get list of S3 buckets.
+// @Tags S3
+// @Produce  json
+// @Success 200 {array} string "List of S3 buckets"
+// @Router /api/s3 [get]
 func apiS3List(c *gin.Context) {
 	keys := []string{}
 	for k := range context.Config().S3PublishRoots {

api/snapshot.go

@@ -12,7 +12,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// GET /api/snapshots
+// @Summary Get snapshots
+// @Description Get list of available snapshots. Each snapshot is returned as in “show” API.
+// @Tags Snapshots
+// @Produce  json
+// @Success 200 {array} deb.Snapshot
+// @Router /api/snapshots [get]
 func apiSnapshotsList(c *gin.Context) {
 	SortMethodString := c.Request.URL.Query().Get("sort")
 

api/task.go

@@ -9,7 +9,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// GET /tasks
+// @Summary Get tasks
+// @Description Get list of available tasks. Each task is returned as in “show” API.
+// @Tags Tasks
+// @Produce  json
+// @Success 200 {array} task.Task
+// @Router /api/tasks [get]
 func apiTasksList(c *gin.Context) {
 	list := context.TaskList()
 	c.JSON(200, list.GetTasks())