swagger: document async

api/db.go

@@ -17,7 +17,7 @@ import (
 // @Description It is a good idea to run this command after massive deletion of mirrors, snapshots or local repos.
 // @Tags Database
 // @Produce json
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} string "Output"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/db/cleanup [post]

api/mirror.go

@@ -164,6 +164,7 @@ func apiMirrorsCreate(c *gin.Context) {
 // @Tags Mirrors
 // @Param name path string true "mirror name"
 // @Param force query int true "force: 1 to enable"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200 {object} task.ProcessReturnValue
 // @Failure 404 {object} Error "Mirror not found"
@@ -364,6 +365,7 @@ type mirrorUpdateParams struct {
 // @Param name path string true "mirror name to update"
 // @Consume json
 // @Param request body mirrorUpdateParams true "Parameters"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200 {object} task.ProcessReturnValue "Mirror was updated successfully"
 // @Success 202 {object} task.Task "Mirror is being updated"

api/publish.go

@@ -188,6 +188,7 @@ type publishedRepoCreateParams struct {
 // @Description See also: `aptly publish create`
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body publishedRepoCreateParams true "Parameters"
 // @Produce json
@@ -395,6 +396,7 @@ type publishedRepoUpdateSwitchParams struct {
 // @Produce json
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body publishedRepoUpdateSwitchParams true "Parameters"
 // @Produce json
@@ -525,6 +527,7 @@ func apiPublishUpdateSwitch(c *gin.Context) {
 // @Param distribution path string true "distribution name"
 // @Param force query int true "force: 1 to enable"
 // @Param skipCleanup query int true "skipCleanup: 1 to enable"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Published repository not found"
@@ -571,6 +574,7 @@ func apiPublishDrop(c *gin.Context) {
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body sourceParams true "Parameters"
 // @Produce json
@@ -688,6 +692,7 @@ func apiPublishListChanges(c *gin.Context) {
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body []sourceParams true "Parameters"
 // @Produce json
@@ -753,6 +758,7 @@ func apiPublishSetSources(c *gin.Context) {
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200
 // @Failure 400 {object} Error "Bad Request"
@@ -805,6 +811,7 @@ func apiPublishDropChanges(c *gin.Context) {
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
 // @Param component path string true "component name"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body sourceParams true "Parameters"
 // @Produce json
@@ -884,6 +891,7 @@ func apiPublishUpdateSource(c *gin.Context) {
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
 // @Param component path string true "component name"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200
 // @Failure 400 {object} Error "Bad Request"
@@ -960,6 +968,7 @@ type publishedRepoUpdateParams struct {
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
 // @Param distribution path string true "distribution name"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Param request body publishedRepoUpdateParams true "Parameters"
 // @Produce json

api/repos.go

@@ -251,7 +251,7 @@ func apiReposShow(c *gin.Context) {
 // @Description Needs force=1 to drop repos used as source by other repos.
 // @Tags Repos
 // @Produce json
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Param force query int false "force: 1 to enable"
 // @Success 200 {object} task.ProcessReturnValue "Repo object"
 // @Failure 404 {object} Error "Not Found"
@@ -403,7 +403,7 @@ func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(li
 // @Tags Repos
 // @Produce json
 // @Param request body reposPackagesAddDeleteParams true "Parameters"
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} string "msg"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
@@ -423,7 +423,7 @@ func apiReposPackagesAdd(c *gin.Context) {
 // @Tags Repos
 // @Produce json
 // @Param request body reposPackagesAddDeleteParams true "Parameters"
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} string "msg"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
@@ -445,7 +445,7 @@ func apiReposPackagesDelete(c *gin.Context) {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200 {string} string "OK"
 // @Failure 400 {object} Error "wrong file"
@@ -467,7 +467,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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce  json
 // @Success 200 {string} string "OK"
 // @Failure 400 {object} Error "wrong file"
@@ -604,7 +604,7 @@ type reposCopyPackageParams struct {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} task.ProcessReturnValue "msg"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
@@ -753,7 +753,7 @@ func apiReposCopyPackage(c *gin.Context) {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/repos/{name}/include/{dir}/{file} [post]
@@ -781,7 +781,7 @@ type reposIncludePackageFromDirResponse struct {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 200 {object} reposIncludePackageFromDirResponse "Response"
 // @Failure 404 {object} Error "Not Found"
 // @Router /api/repos/{name}/include/{dir} [post]

api/snapshot.go

@@ -52,7 +52,7 @@ type snapshotsCreateFromMirrorParams struct {
 // @Produce json
 // @Param request body snapshotsCreateFromMirrorParams true "Parameters"
 // @Param name path string true "Mirror name"
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 201 {object} deb.Snapshot "Created Snapshot"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Mirror Not Found"
@@ -126,7 +126,7 @@ type snapshotsCreateParams struct {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 201 {object} deb.Snapshot "Created snapshot"
 // @Failure 400 {object} Error "Bad Request"
@@ -213,7 +213,7 @@ type snapshotsCreateFromRepositoryParams struct {
 // @Consume json
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 201 {object} deb.Snapshot "Created snapshot object"
 // @Failure 400 {object} Error "Bad Request"
@@ -279,7 +279,7 @@ type snapshotsUpdateParams struct {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200 {object} deb.Snapshot "Updated snapshot object"
 // @Failure 404 {object} Error "Snapshot Not Found"
@@ -366,7 +366,7 @@ func apiSnapshotsShow(c *gin.Context) {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Produce json
 // @Success 200 ""
 // @Failure 404 {object} Error "Snapshot Not Found"
@@ -525,7 +525,7 @@ type snapshotsMergeParams struct {
 // @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"
 // @Param request body snapshotsMergeParams true "Parameters"
-// @Param _async query bool false "Run task in background using tasks API"
+// @Param _async query bool false "Run in background and return task object"
 // @Success 201 {object} deb.Snapshot "Resulting snapshot object"
 // @Failure 400 {object} Error "Bad Request"
 // @Failure 404 {object} Error "Not Found"
@@ -637,7 +637,7 @@ type snapshotsPullParams struct {
 // @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"
+// @Param _async query bool false "Run in background and return task object"
 // @Consume json
 // @Produce json
 // @Success 200 {object} deb.Snapshot "Resulting Snapshot object"

docs/Publish.md

@@ -1,4 +1,4 @@
-# Publish Repositories and Mirrors
+# Publish Repositories, Snapshots, Mirrors
 <div>
 
 Publish snapshot or local repo as Debian repository to be used as APT source on Debian based systems.

docs/Snapshots.md

@@ -1,4 +1,4 @@
-# Manage Snapshots of Repositories and Mirrors
+# Manage Snapshots
 <div>
 
 Local Repositories and Mirrors can be snapshotted to get an immutable state.