Update repos, task, snapshot api docs

Makefile

@@ -58,7 +58,7 @@ azurite-stop:
 
 swagger: swagger-install
 	# Generate swagger docs
-	@PATH=$(BINPATH)/:$(PATH) swag init --markdownFiles docs --generalInfo docs/swagger.conf
+	@PATH=$(BINPATH)/:$(PATH) swag init --parseDependency --parseInternal --markdownFiles docs --generalInfo docs/swagger.conf
 
 etcd-install:
 	# Install etcd

api/repos.go

@@ -18,13 +18,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// @Summary TODO
+// @Summary Serve HTML listing of repo
-// @Description **ToDo**
+// @Description If ServeInAPIMode is enabled in aptly config,
-// @Description To Do
+// @Description this endpoint is enabled which returns an HTML listing of each repo that can be browsed
 // @Tags Repos
-// @Produce json
+// @Produce html
-// @Success 200 {object} string "msg"
+// @Success 200 {object} string "HTML"
-// @Failure 404 {object} Error "Not Found"
 // @Router /api/repos [get]
 func reposListInAPIMode(localRepos map[string]utils.FileSystemPublishRoot) gin.HandlerFunc {
 	return func(c *gin.Context) {
@@ -42,15 +41,14 @@ func reposListInAPIMode(localRepos map[string]utils.FileSystemPublishRoot) gin.H
 	}
 }
 
-// @Summary TODO
+// @Summary Serve package in API mode
-// @Description **ToDo**
+// @Description If ServeInAPIMode is enabled in aptly config,
-// @Description To Do
+// @Description this api serves a specified package from storage
 // @Tags Repos
 // @Param storage path string true "Storage"
 // @Param pkgPath path string true "Package Path" allowReserved=true
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 ""
-// @Failure 404 {object} Error "Not Found"
 // @Router /api/{storage}/{pkgPath} [get]
 func reposServeInAPIMode(c *gin.Context) {
 	pkgpath := c.Param("pkgPath")
@@ -100,7 +98,8 @@ type repoCreateParams struct {
 }
 
 // @Summary Create repository
-// @Description Create a local repository.
+// @Description Create a local repository with specified parameters.
+// @Description Distribution and component are used as defaults when publishing repo either directly or via snapshot.
 // @Tags Repos
 // @Produce  json
 // @Consume  json
@@ -159,22 +158,24 @@ func apiReposCreate(c *gin.Context) {
 	c.JSON(http.StatusCreated, repo)
 }
 
-// @Summary TODO
+type reposEditParams struct {
-// @Description **ToDo**
+	Name                *string
-// @Description To Do
+	Comment             *string
+	DefaultDistribution *string
+	DefaultComponent    *string
+}
+
+// @Summary Update repo
+// @Description **Update local repository meta information**
 // @Tags Repos
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param request body reposEditParams true "Parameters"
+// @Success 200 {object} deb.LocalRepo "msg"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/repos/{name} [put]
 func apiReposEdit(c *gin.Context) {
-	var b struct {
+	var b reposEditParams
-		Name                *string
-		Comment             *string
-		DefaultDistribution *string
-		DefaultComponent    *string
-	}
-
 	if c.Bind(&b) != nil {
 		return
 	}
@@ -238,13 +239,17 @@ func apiReposShow(c *gin.Context) {
 	c.JSON(200, repo)
 }
 
-// @Summary TODO
+// @Summary Drop Repository
-// @Description **ToDo**
+// @Description Drop/delete a repo
-// @Description To Do
+// @Description Cannot drop repos that are published.
+// @Description Needs force=1 to drop repos used as source by other repos.
 // @Tags Repos
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param _async query bool false "Run task in background using tasks API"
+// @Param force query int false "force: 1 to enable"
+// @Success 200 {object} task.ProcessReturnValue "Repo object"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 404 {object} Error "Repo Conflict"
 // @Router /api/repos/{name} [delete]
 func apiReposDrop(c *gin.Context) {
 	force := c.Request.URL.Query().Get("force") == "1"
@@ -280,13 +285,19 @@ func apiReposDrop(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+// @Summary List Repo Packages
-// @Description **ToDo**
+// @Description **Return a list of packages present in the repo**
-// @Description To Do
+// @Description If `q` query parameter is missing, return all packages, otherwise return packages that match q
 // @Tags Repos
 // @Produce json
+// @Param name path string true "Snapshot to search"
+// @Param q query string true "Package query (e.g Name%20(~%20matlab))"
+// @Param withDeps query string true "Set to 1 to include dependencies when evaluating package query"
+// @Param format query string true "Set to 'details' to return extra info about each package"
+// @Param maximumVersion query string true "Set to 1 to only return the highest version for each package name"
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 404 {object} Error "Internal Server Error"
 // @Router /api/repos/{name}/packages [get]
 func apiReposPackagesShow(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
@@ -307,11 +318,13 @@ func apiReposPackagesShow(c *gin.Context) {
 	showPackages(c, repo.RefList(), collectionFactory)
 }
 
+type reposPackagesAddDeleteParams struct {
+	PackageRefs []string
+}
+
 // Handler for both add and delete
 func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error) {
-	var b struct {
+	var b reposPackagesAddDeleteParams
-		PackageRefs []string
-	}
 
 	if c.Bind(&b) != nil {
 		return
@@ -368,13 +381,20 @@ func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(li
 	})
 }
 
-// @Summary TODO
+// @Summary Add Packages by Key
-// @Description **ToDo**
+// @Description **Add packages to local repository by package keys.**
-// @Description To Do
+// @Description
+// @Description Any package can be added that is present in the aptly database (from any mirror, snapshot, local repository). This API combined with package list (search) APIs allows one to implement importing, copying, moving packages around.
+// @Description
+// @Description API verifies that packages actually exist in aptly database and checks constraint that conflicting packages can’t be part of the same local repository.
 // @Tags Repos
 // @Produce json
+// @Param request body reposPackagesAddDeleteParams true "Parameters"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Success 200 {object} string "msg"
+// @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 400 {object} Error "Internal Server Error"
 // @Router /api/repos/{name}/packages [post]
 func apiReposPackagesAdd(c *gin.Context) {
 	apiReposPackagesAddDelete(c, "Add packages to repo ", func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error {
@@ -383,13 +403,18 @@ func apiReposPackagesAdd(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+// @Summary Delete Packages by Key
-// @Description **ToDo**
+// @Description **Remove packages from local repository by package keys.**
-// @Description To Do
+// @Description
+// @Description Any package(s) can be removed from a local repository. Package references from a local repository can be retrieved with GET /api/repos/:name/packages.
 // @Tags Repos
 // @Produce json
+// @Param request body reposPackagesAddDeleteParams true "Parameters"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Success 200 {object} string "msg"
+// @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 400 {object} Error "Internal Server Error"
 // @Router /api/repos/{name}/packages [delete]
 func apiReposPackagesDelete(c *gin.Context) {
 	apiReposPackagesAddDelete(c, "Delete packages from repo ", func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error {
@@ -399,23 +424,27 @@ func apiReposPackagesDelete(c *gin.Context) {
 	})
 }
 
-// @Summary Add packages
+// @Summary Add packages from uploaded file
-// @Description **Add package file**
+// @Description Import packages from files (uploaded using File Upload API) to the local repository. If directory specified, aptly would discover package files automatically.
-// @Description To Do
+// @Description Adding same package to local repository is not an error.
+// @Description By default aptly would try to remove every successfully processed file and directory `dir` (if it becomes empty after import).
 // @Tags Repos
 // @Param name path string true "Repository name"
 // @Param dir path string true "Directory of packages"
 // @Param file path string false "Filename (optional)"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 {string} string "OK"
-// @Failure 404 {object} Error "Not Found"
+// @Failure 400 {object} Error "wrong file"
+// @Failure 404 {object} Error "Repository not found"
+// @Failure 500 {object} Error "Error adding files"
 // @Router /api/repos/{name}/file/{dir}/{file} [post]
 func apiReposPackageFromFile(c *gin.Context) {
 	// redirect all work to dir method
 	apiReposPackageFromDir(c)
 }
 
-// @Summary Add packages from uploaded file/directory
+// @Summary Add packages from uploaded directory
 // @Description Import packages from files (uploaded using File Upload API) to the local repository. If directory specified, aptly would discover package files automatically.
 // @Description Adding same package to local repository is not an error.
 // @Description By default aptly would try to remove every successfully processed file and directory `dir` (if it becomes empty after import).
@@ -425,6 +454,7 @@ func apiReposPackageFromFile(c *gin.Context) {
 // @Consume  json
 // @Param noRemove query string false "when value is set to 1, don’t remove any files"
 // @Param forceReplace query string false "when value is set to 1, remove packages conflicting with package being added (in local repository)"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce  json
 // @Success 200 {string} string "OK"
 // @Failure 400 {object} Error "wrong file"
@@ -549,23 +579,31 @@ func apiReposPackageFromDir(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+type reposCopyPackageParams struct {
-// @Description **ToDo**
+	WithDeps bool `json:"with-deps,omitempty"`
-// @Description To Do
+	DryRun   bool `json:"dry-run,omitempty"`
+}
+
+// @Summary Copy Package
+// @Description Copies a package from a source to destination repository
 // @Tags Repos
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param name path string true "Source repo"
+// @Param src path string true "Destination repo"
+// @Param file path string true "File/packages to copy"
+// @Param _async query bool false "Run task in background using tasks API"
+// @Success 200 {object} task.ProcessReturnValue "msg"
+// @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
+// @Failure 422 {object} Error "Unprocessable Entity"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/repos/{name}/copy/{src}/{file} [post]
 func apiReposCopyPackage(c *gin.Context) {
 	dstRepoName := c.Params.ByName("name")
 	srcRepoName := c.Params.ByName("src")
 	fileName := c.Params.ByName("file")
 
-	jsonBody := struct {
+	jsonBody := reposCopyPackageParams{
-		WithDeps bool `json:"with-deps,omitempty"`
-		DryRun   bool `json:"dry-run,omitempty"`
-	}{
 		WithDeps: false,
 		DryRun:   false,
 	}
@@ -619,7 +657,6 @@ func apiReposCopyPackage(c *gin.Context) {
 		dstList, err := deb.NewPackageListFromRefList(dstRepo.RefList(), collectionFactory.PackageCollection(), context.Progress())
 		if err != nil {
 			return &task.ProcessReturnValue{Code: http.StatusInternalServerError, Value: nil}, fmt.Errorf("unable to load packages in dest: %s", err)
-
 		}
 
 		srcList, err := deb.NewPackageListFromRefList(srcRefList, collectionFactory.PackageCollection(), context.Progress())
@@ -695,11 +732,15 @@ func apiReposCopyPackage(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+// @Summary Include Packages from File Upload
-// @Description **ToDo**
+// @Description Allows automatic processing of .changes file controlling package upload (uploaded using File Upload API) to the local repository. i.e. Exposes repo include command in api.
-// @Description To Do
 // @Tags Repos
 // @Produce json
+// @Param forceReplace query int false "when value is set to 1, when adding package that conflicts with existing package, remove existing package"
+// @Param noRemoveFiles query int false "when value is set to 1, don’t remove files that have been imported successfully into repository"
+// @Param acceptUnsigned query int false "when value is set to 1, accept unsigned .changes files"
+// @Param ignoreSignature query int false "when value is set to 1 disable verification of .changes file signature"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/repos/{name}/include/{dir}/{file} [post]
@@ -708,12 +749,27 @@ func apiReposIncludePackageFromFile(c *gin.Context) {
 	apiReposIncludePackageFromDir(c)
 }
 
-// @Summary TODO
+type reposIncludePackageFromDirReport struct {
-// @Description **ToDo**
+	Warnings []string
-// @Description To Do
+	Added    []string
+	Deleted  []string
+}
+
+type reposIncludePackageFromDirResponse struct {
+	Report      reposIncludePackageFromDirReport
+	FailedFiles []string
+}
+
+// @Summary Include Packages from Dir Upload
+// @Description Allows automatic processing of .changes file controlling package upload (uploaded using File Upload API) to the local repository. i.e. Exposes repo include command in api.
 // @Tags Repos
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param forceReplace query int false "when value is set to 1, when adding package that conflicts with existing package, remove existing package"
+// @Param noRemoveFiles query int false "when value is set to 1, don’t remove files that have been imported successfully into repository"
+// @Param acceptUnsigned query int false "when value is set to 1, accept unsigned .changes files"
+// @Param ignoreSignature query int false "when value is set to 1 disable verification of .changes file signature"
+// @Param _async query bool false "Run task in background using tasks API"
+// @Success 200 {object} reposIncludePackageFromDirResponse "Response"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/repos/{name}/include/{dir} [post]
 func apiReposIncludePackageFromDir(c *gin.Context) {
@@ -817,6 +873,5 @@ func apiReposIncludePackageFromDir(c *gin.Context) {
 			"Report":      reporter,
 			"FailedFiles": failedFiles,
 		}}, nil
-
 	})
 }

api/snapshot.go

@@ -15,7 +15,8 @@ import (
 )
 
 // @Summary Get snapshots
-// @Description Get list of available snapshots. Each snapshot is returned as in “show” API.
+// @Description **Get list of available snapshots**
+// @Description Each snapshot is returned as in “show” API.
 // @Tags Snapshots
 // @Produce  json
 // @Success 200 {array} deb.Snapshot
@@ -39,26 +40,32 @@ func apiSnapshotsList(c *gin.Context) {
 	c.JSON(200, result)
 }
 
-// @Summary TODO
+type snapshotsCreateFromMirrorParams struct {
-// @Description **ToDo**
+	Name        string `binding:"required"`
-// @Description To Do
+	Description string
+}
+
+// @Summary Create snapshot from mirror
+// @Description **Create snapshot of a mirror from given name**
 // @Tags Snapshots
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param request body snapshotsCreateFromMirrorParams true "Parameters"
-// @Failure 404 {object} Error "Not Found"
+// @Param name path string true "Mirror name"
+// @Param _async query bool false "Run task in background using tasks API"
+// @Success 201 {object} deb.Snapshot "Created Snapshot"
+// @Failure 400 {object} Error "Bad Request"
+// @Failure 404 {object} Error "Mirror Not Found"
+// @Failure 409 {object} Error "Conflicting snapshot"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/mirrors/{name}/snapshots [post]
 func apiSnapshotsCreateFromMirror(c *gin.Context) {
 	var (
 		err      error
 		repo     *deb.RemoteRepo
 		snapshot *deb.Snapshot
+		b        snapshotsCreateFromMirrorParams
 	)
 
-	var b struct {
-		Name        string `binding:"required"`
-		Description string
-	}
-
 	if c.Bind(&b) != nil {
 		return
 	}
@@ -105,27 +112,32 @@ func apiSnapshotsCreateFromMirror(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+type snapshotsCreateParams struct {
-// @Description **ToDo**
+	Name            string `binding:"required"`
-// @Description To Do
+	Description     string
+	SourceSnapshots []string
+	PackageRefs     []string
+}
+
+// @Summary Create snapshot from repo
+// @Description **Create a snapshot from package refs**
+// @Description Refs can be obtained from snapshots, local repos, or mirrors
 // @Tags Snapshots
+// @Param request body snapshotsCreateParams true "Parameters"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 201 {object} deb.Snapshot "Created snapshot"
-// @Failure 404 {object} Error "Not Found"
+// @Failure 400 {object} Error "Bad Request"
+// @Failure 404 {object} Error "Source snapshot or package refs not found"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots [post]
 func apiSnapshotsCreate(c *gin.Context) {
 	var (
 		err      error
 		snapshot *deb.Snapshot
+		b        snapshotsCreateParams
 	)
 
-	var b struct {
-		Name            string `binding:"required"`
-		Description     string
-		SourceSnapshots []string
-		PackageRefs     []string
-	}
-
 	if c.Bind(&b) != nil {
 		return
 	}
@@ -187,28 +199,31 @@ func apiSnapshotsCreate(c *gin.Context) {
 	})
 }
 
-type snapshotRepositoryParams struct {
+type snapshotsCreateFromRepositoryParams struct {
 	Name        string `binding:"required"`
 	Description string
 }
 
 // @Summary Snapshot Repository
-// @Description **Create a sbalshot of a repository**
+// @Description **Create a snapshot of a repository by name**
-// @Description To Do
 // @Tags Snapshots
 // @Param name path string true "Repository name"
 // @Consume json
-// @Param request body snapshotRepositoryParams true "Parameters"
+// @Param request body snapshotsCreateFromRepositoryParams true "Parameters"
+// @Param name path string true "Name of the snapshot"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 201 {object} deb.Snapshot "Created snapshot object"
-// @Failure 404 {object} Error "Not Found"
+// @Failure 400 {object} Error "Bad Request"
+// @Failure 500 {object} Error "Internal Server Error"
+// @Failure 404 {object} Error "Repo Not Found"
 // @Router /api/repos/{name}/snapshots [post]
 func apiSnapshotsCreateFromRepository(c *gin.Context) {
 	var (
 		err      error
 		repo     *deb.LocalRepo
 		snapshot *deb.Snapshot
-		b        snapshotRepositoryParams
+		b        snapshotsCreateFromRepositoryParams
 	)
 
 	if c.Bind(&b) != nil {
@@ -252,25 +267,30 @@ func apiSnapshotsCreateFromRepository(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+type snapshotsUpdateParams struct {
-// @Description **ToDo**
+	Name        string
-// @Description To Do
+	Description string
+}
+
+// @Summary Update Snapshot
+// @Description **Update snapshot metadata (Name, Description)**
 // @Tags Snapshots
+// @Param request body snapshotsUpdateParams true "Parameters"
+// @Param name path string true "Snapshot name"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 {object} deb.Snapshot "Updated snapshot object"
-// @Failure 404 {object} Error "Not Found"
+// @Failure 404 {object} Error "Snapshot Not Found"
+// @Failure 409 {object} Error "Conflicting snapshot"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots/{name} [put]
 func apiSnapshotsUpdate(c *gin.Context) {
 	var (
 		err      error
 		snapshot *deb.Snapshot
+		b        snapshotsUpdateParams
 	)
 
-	var b struct {
-		Name        string
-		Description string
-	}
-
 	if c.Bind(&b) != nil {
 		return
 	}
@@ -310,13 +330,13 @@ func apiSnapshotsUpdate(c *gin.Context) {
 }
 
 // @Summary Get snapshot information
-// @Description **Get information about a snapshot**
+// @Description **Query detailed information about a snapshot by name**
-// @Description To Do
 // @Tags Snapshots
 // @Param name path string true "Name of the snapshot"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 {object} deb.Snapshot "msg"
-// @Failure 404 {object} Error "Not Found"
+// @Failure 404 {object} Error "Snapshot Not Found"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots/{name} [get]
 func apiSnapshotsShow(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
@@ -337,13 +357,19 @@ func apiSnapshotsShow(c *gin.Context) {
 	c.JSON(200, snapshot)
 }
 
-// @Summary TODO
+// @Summary Drop Snapshot
-// @Description **ToDo**
+// @Description **Drop/delete snapshot by name**
-// @Description To Do
+// @Description Cannot drop snapshots that are published.
+// @Description Needs force=1 to drop snapshots used as source by other snapshots.
 // @Tags Snapshots
+// @Param name path string true "Snapshot name"
+// @Param force query string false "Force operation"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 ""
-// @Failure 404 {object} Error "Not Found"
+// @Failure 404 {object} Error "Snapshot Not Found"
+// @Failure 409 {object} Error "Snapshot in use"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots/{name} [delete]
 func apiSnapshotsDrop(c *gin.Context) {
 	name := c.Params.ByName("name")
@@ -383,13 +409,18 @@ func apiSnapshotsDrop(c *gin.Context) {
 	})
 }
 
-// @Summary TODO
+// @Summary Snapshot diff
-// @Description **ToDo**
+// @Description **Return the diff between two snapshots (name & withSnapshot)**
-// @Description To Do
+// @Description Provide `onlyMatching=1` to return only packages present in both snapshots.
+// @Description Otherwise, returns a `left` and `right` result providing packages only in the first and second snapshots
 // @Tags Snapshots
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param name path string true "Snapshot name"
-// @Failure 404 {object} Error "Not Found"
+// @Param withSnapshot path string true "Snapshot name to diff against"
+// @Param onlyMatching query string false "Only return packages present in both snapshots"
+// @Success 200 {array} deb.PackageDiff "Package Diff"
+// @Failure 404 {object} Error "Snapshot Not Found"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots/{name}/diff/{withSnapshot} [get]
 func apiSnapshotsDiff(c *gin.Context) {
 	onlyMatching := c.Request.URL.Query().Get("onlyMatching") == "1"
@@ -441,13 +472,19 @@ func apiSnapshotsDiff(c *gin.Context) {
 	c.JSON(200, result)
 }
 
-// @Summary TODO
+// @Summary List Snapshot Packages
-// @Description **ToDo**
+// @Description **List all packages in snapshot or perform search on snapshot contents and return results**
-// @Description To Do
+// @Description If `q` query parameter is missing, return all packages, otherwise return packages that match q
 // @Tags Snapshots
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param name path string true "Snapshot to search"
-// @Failure 404 {object} Error "Not Found"
+// @Param q query string false "Package query (e.g Name%20(~%20matlab))"
+// @Param withDeps query string false "Set to 1 to include dependencies when evaluating package query"
+// @Param format query string false "Set to 'details' to return extra info about each package"
+// @Param maximumVersion query string false "Set to 1 to only return the highest version for each package name"
+// @Success 200 {array} string "Package info"
+// @Failure 404 {object} Error "Snapshot Not Found"
+// @Failure 500 {object} Error "Internal Server Error"
 // @Router /api/snapshots/{name}/packages [get]
 func apiSnapshotsSearchPackages(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
@@ -480,13 +517,14 @@ type snapshotsMergeParams struct {
 // @Description
 // @Description If only one snapshot is specified, merge copies source into destination.
 // @Tags Snapshots
+// @Consume json
+// @Produce json
 // @Param name path string true "Name of the snapshot to be created"
 // @Param latest query int false "merge only the latest version of each package"
 // @Param no-remove query int false "all versions of packages are preserved during merge"
-// @Consume json
 // @Param request body snapshotsMergeParams true "Parameters"
-// @Produce  json
+// @Param _async query bool false "Run task in background using tasks API"
-// @Success 200
+// @Success 201 {object} deb.Snapshot "Resulting snapshot object"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
 // @Failure 500 {object} Error "Internal Error"
@@ -591,15 +629,16 @@ type snapshotsPullParams struct {
 // @Description
 // @Description Aptly pulls first package matching each of package queries, but with flag -all-matches all matching packages would be pulled.
 // @Tags Snapshots
+// @Param request body snapshotsPullParams true "Parameters"
 // @Param name path string true "Name of the snapshot to be created"
 // @Param all-matches query int false "pull all the packages that satisfy the dependency version requirements (default is to pull first matching package): 1 to enable"
 // @Param dry-run query int false "don’t create destination snapshot, just show what would be pulled: 1 to enable"
 // @Param no-deps query int false "don’t process dependencies, just pull listed packages: 1 to enable"
 // @Param no-remove query int false "don’t remove other package versions when pulling package: 1 to enable"
+// @Param _async query bool false "Run task in background using tasks API"
 // @Consume json
-// @Param request body snapshotsPullParams true "Parameters"
 // @Produce json
-// @Success 200
+// @Success 200 {object} deb.Snapshot "Resulting Snapshot object"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
 // @Failure 500 {object} Error "Internal Error"

api/task.go

@@ -10,9 +10,9 @@ import (
 )
 
 // @Summary Get tasks
-// @Description Get list of available tasks. Each task is returned as in “show” API.
+// @Description **Get list of available tasks. Each task is returned as in “show” API**
 // @Tags Tasks
-// @Produce  json
+// @Produce json
 // @Success 200 {array} task.Task
 // @Router /api/tasks [get]
 func apiTasksList(c *gin.Context) {
@@ -20,12 +20,11 @@ func apiTasksList(c *gin.Context) {
 	c.JSON(200, list.GetTasks())
 }
 
-// @Summary TODO
+// @Summary Clear finished and failed tasks
-// @Description **ToDo**
+// @Description **Removes finished and failed tasks from internal task list**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 ""
 // @Router /api/tasks-clear [post]
 func apiTasksClear(c *gin.Context) {
 	list := context.TaskList()
@@ -33,13 +32,11 @@ func apiTasksClear(c *gin.Context) {
 	c.JSON(200, gin.H{})
 }
 
-// @Summary TODO
+// @Summary Wait for task completion
-// @Description **ToDo**
+// @Description **Waits for and returns when all running tasks are complete**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Success 200 ""
-// @Failure 404 {object} Error "Not Found"
 // @Router /api/tasks-wait [get]
 func apiTasksWait(c *gin.Context) {
 	list := context.TaskList()
@@ -47,13 +44,14 @@ func apiTasksWait(c *gin.Context) {
 	c.JSON(200, gin.H{})
 }
 
-// @Summary TODO
+// @Summary Wait for task to process
-// @Description **ToDo**
+// @Description **Waits for and returns when given Task ID is complete**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param id path int true "Task ID"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} task.Task
+// @Failure 500 {object} Error "invalid syntax, bad id?"
+// @Failure 400 {object} Error "Task Not Found"
 // @Router /api/tasks/{id}/wait [get]
 func apiTasksWaitForTaskByID(c *gin.Context) {
 	list := context.TaskList()
@@ -72,13 +70,14 @@ func apiTasksWaitForTaskByID(c *gin.Context) {
 	c.JSON(200, task)
 }
 
-// @Summary TODO
+// @Summary Return task information
-// @Description **ToDo**
+// @Description **Return task information for a given ID**
-// @Description To Do
 // @Tags Tasks
-// @Produce json
+// @Produce plain
-// @Success 200 {object} string "msg"
+// @Param id path int true "Task ID"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} task.Task
+// @Failure 500 {object} Error "invalid syntax, bad id?"
+// @Failure 404 {object} Error "Task Not Found"
 // @Router /api/tasks/{id} [get]
 func apiTasksShow(c *gin.Context) {
 	list := context.TaskList()
@@ -98,13 +97,14 @@ func apiTasksShow(c *gin.Context) {
 	c.JSON(200, task)
 }
 
-// @Summary TODO
+// @Summary Return task output
-// @Description **ToDo**
+// @Description **Return task output for a given ID**
-// @Description To Do
 // @Tags Tasks
-// @Produce json
+// @Produce plain
-// @Success 200 {object} string "msg"
+// @Param id path int true "Task ID"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} string "Task output"
+// @Failure 500 {object} Error "invalid syntax, bad ID?"
+// @Failure 404 {object} Error "Task Not Found"
 // @Router /api/tasks/{id}/output [get]
 func apiTasksOutputShow(c *gin.Context) {
 	list := context.TaskList()
@@ -124,13 +124,14 @@ func apiTasksOutputShow(c *gin.Context) {
 	c.JSON(200, output)
 }
 
-// @Summary TODO
+// @Summary Return task detail
-// @Description **ToDo**
+// @Description **Return task detail for a given ID**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param id path int true "Task ID"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} string "Task detail"
+// @Failure 500 {object} Error "invalid syntax, bad ID?"
+// @Failure 404 {object} Error "Task Not Found"
 // @Router /api/tasks/{id}/detail [get]
 func apiTasksDetailShow(c *gin.Context) {
 	list := context.TaskList()
@@ -150,12 +151,13 @@ func apiTasksDetailShow(c *gin.Context) {
 	c.JSON(200, detail)
 }
 
-// @Summary TODO
+// @Summary Return task return value (status code)
-// @Description **ToDo**
+// @Description **Return task return value (status code) by given ID**
-// @Description To Do
 // @Tags Tasks
-// @Produce json
+// @Produce plain
+// @Param id path int true "Task ID"
 // @Success 200 {object} string "msg"
+// @Failure 500 {object} Error "invalid syntax, bad ID?"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/tasks/{id}/return_value [get]
 func apiTasksReturnValueShow(c *gin.Context) {
@@ -175,13 +177,14 @@ func apiTasksReturnValueShow(c *gin.Context) {
 	c.JSON(200, output)
 }
 
-// @Summary TODO
+// @Summary Delete task
-// @Description **ToDo**
+// @Description **Delete completed task by given ID. Does not stop task execution**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param id path int true "Task ID"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} task.Task
+// @Failure 500 {object} Error "invalid syntax, bad ID?"
+// @Failure 400 {object} Error "Task in progress or not found"
 // @Router /api/tasks/{id} [delete]
 func apiTasksDelete(c *gin.Context) {
 	list := context.TaskList()
@@ -201,15 +204,12 @@ func apiTasksDelete(c *gin.Context) {
 	c.JSON(200, delTask)
 }
 
-// FIXME: used for testing only, remove:
+// @Summary Dummy endpoint used for testing.
-
+// @Description **Dummy endpoint used for testing**
-// @Summary TODO
-// @Description **ToDo**
-// @Description To Do
 // @Tags Tasks
 // @Produce json
-// @Success 200 {object} string "msg"
+// @Param _async query bool false "Run task in background using tasks API"
-// @Failure 404 {object} Error "Not Found"
+// @Success 200 {object} task.ProcessReturnValue
 // @Router /api/tasks-dummy [post]
 func apiTasksDummy(c *gin.Context) {
 	resources := []string{"dummy"}