From e5e3c49aced1dd872ee7576082c194c4bd4042cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Roth?= Date: Thu, 28 Nov 2024 16:07:33 +0100 Subject: [PATCH] swagger: document async --- api/db.go | 2 +- api/mirror.go | 2 ++ api/publish.go | 9 +++++++++ api/repos.go | 16 ++++++++-------- api/snapshot.go | 14 +++++++------- docs/Publish.md | 2 +- docs/Snapshots.md | 2 +- 7 files changed, 29 insertions(+), 18 deletions(-) diff --git a/api/db.go b/api/db.go index f6d0e5a8..259a94aa 100644 --- a/api/db.go +++ b/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] diff --git a/api/mirror.go b/api/mirror.go index f121d2bf..48a505fe 100644 --- a/api/mirror.go +++ b/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" diff --git a/api/publish.go b/api/publish.go index 9303b382..453f9a3d 100644 --- a/api/publish.go +++ b/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 diff --git a/api/repos.go b/api/repos.go index 93475337..1069be13 100644 --- a/api/repos.go +++ b/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] diff --git a/api/snapshot.go b/api/snapshot.go index 6138b3de..327f22db 100644 --- a/api/snapshot.go +++ b/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" diff --git a/docs/Publish.md b/docs/Publish.md index 3e497a67..0077f4d9 100644 --- a/docs/Publish.md +++ b/docs/Publish.md @@ -1,4 +1,4 @@ -# Publish Repositories and Mirrors +# Publish Repositories, Snapshots, Mirrors
Publish snapshot or local repo as Debian repository to be used as APT source on Debian based systems. diff --git a/docs/Snapshots.md b/docs/Snapshots.md index d6db4a4d..21d0e526 100644 --- a/docs/Snapshots.md +++ b/docs/Snapshots.md @@ -1,4 +1,4 @@ -# Manage Snapshots of Repositories and Mirrors +# Manage Snapshots
Local Repositories and Mirrors can be snapshotted to get an immutable state.