From e319f3cd14a20ef9a40478afa3f78f4dfa63bcac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Roth?= Date: Wed, 11 Dec 2024 11:19:21 +0100 Subject: [PATCH] update doc make descrptions consistent --- api/api.go | 6 +++--- api/mirror.go | 4 ++-- api/packages.go | 6 +++--- api/publish.go | 6 +++--- api/repos.go | 22 +++++++++++----------- api/snapshot.go | 6 +++--- api/task.go | 18 +++++++++--------- 7 files changed, 34 insertions(+), 34 deletions(-) diff --git a/api/api.go b/api/api.go index adeef9d9..1c9883f9 100644 --- a/api/api.go +++ b/api/api.go @@ -28,7 +28,7 @@ type aptlyVersion struct { Version string `json:"Version"` } -// @Summary Aptly version +// @Summary Aptly Version // @Description **Get aptly version** // @Description // @Description **Example:** @@ -49,7 +49,7 @@ type aptlyStatus struct { Status string `json:"Status" example:"'Aptly is ready', 'Aptly is unavailable', 'Aptly is healthy'"` } -// @Summary Ready State +// @Summary Get Ready State // @Description **Get aptly ready state** // @Description // @Description Return aptly ready state: @@ -71,7 +71,7 @@ func apiReady(isReady *atomic.Value) func(*gin.Context) { } } -// @Summary Health State +// @Summary Get Health State // @Description **Get aptly health state** // @Description // @Description Return aptly health state: diff --git a/api/mirror.go b/api/mirror.go index 48a505fe..b9adf24c 100644 --- a/api/mirror.go +++ b/api/mirror.go @@ -31,7 +31,7 @@ func getVerifier(keyRings []string) (pgp.Verifier, error) { return verifier, nil } -// @Summary Get Mirrors +// @Summary List Mirrors // @Description **Show list of currently available mirrors** // @Description Each mirror is returned as in “show” API. // @Tags Mirrors @@ -209,7 +209,7 @@ func apiMirrorsDrop(c *gin.Context) { }) } -// @Summary Show Mirror +// @Summary Get Mirror Info // @Description **Get mirror information by name** // @Tags Mirrors // @Param name path string true "mirror name" diff --git a/api/packages.go b/api/packages.go index 631d3014..e29d1fa5 100644 --- a/api/packages.go +++ b/api/packages.go @@ -5,7 +5,7 @@ import ( "github.com/gin-gonic/gin" ) -// @Summary Show packages +// @Summary Get Package Info // @Description **Show information about package by package key** // @Description Package keys could be obtained from various GET .../packages APIs. // @Tags Packages @@ -25,8 +25,8 @@ func apiPackagesShow(c *gin.Context) { c.JSON(200, p) } -// @Summary Get packages -// @Description Get list of packages. +// @Summary List Packages +// @Description **Get list of packages** // @Tags Packages // @Consume json // @Produce json diff --git a/api/publish.go b/api/publish.go index 453f9a3d..e19afb17 100644 --- a/api/publish.go +++ b/api/publish.go @@ -635,7 +635,7 @@ func apiPublishAddSource(c *gin.Context) { }) } -// @Summary List pending changes +// @Summary List Pending Changes // @Description **List source component changes to be applied** // @Description // @Description Return added, removed or changed components of snapshots or local repository to be published. @@ -749,8 +749,8 @@ func apiPublishSetSources(c *gin.Context) { }) } -// @Summary Drop pending changes -// @Description **Drop pending source component changes of a published repository** +// @Summary Discard Pending Changes +// @Description **Discard pending source component changes of a published repository** // @Description // @Description Remove all pending changes what would be applied with a subsequent publish update call (i.e. `PUT /api/publish/{prefix}/{distribution}` / `POST /api/publish/{prefix}/{distribution}/update`). // @Description diff --git a/api/repos.go b/api/repos.go index 3acc29ea..4359b81e 100644 --- a/api/repos.go +++ b/api/repos.go @@ -18,7 +18,7 @@ import ( "github.com/gin-gonic/gin" ) -// @Summary Serve HTML listing of repo +// @Summary Serve HTML Listing // @Description If ServeInAPIMode is enabled in aptly config, // @Description this endpoint is enabled which returns an HTML listing of each repo that can be browsed // @Tags Repos @@ -41,7 +41,7 @@ func reposListInAPIMode(localRepos map[string]utils.FileSystemPublishRoot) gin.H } } -// @Summary Serve package in API mode +// @Summary Serve Packages // @Description If ServeInAPIMode is enabled in aptly config, // @Description this api serves a specified package from storage // @Tags Repos @@ -64,7 +64,7 @@ func reposServeInAPIMode(c *gin.Context) { c.FileFromFS(pkgpath, http.Dir(publicPath)) } -// @Summary Get repos +// @Summary List Repositories // @Description **Get list of available repos** // @Description Each repo is returned as in “show” API. // @Tags Repos @@ -97,7 +97,7 @@ type repoCreateParams struct { FromSnapshot string ` json:"FromSnapshot" example:"snapshot1"` } -// @Summary Create repository +// @Summary Create Repository // @Description **Create a local repository** // @Description // @Description Distribution and component are used as defaults when publishing repo either directly or via snapshot. @@ -175,7 +175,7 @@ type reposEditParams struct { DefaultComponent *string ` json:"DefaultComponent" example:""` } -// @Summary Update repo +// @Summary Update Repository // @Description **Update local repository meta information** // @Tags Repos // @Produce json @@ -228,7 +228,7 @@ func apiReposEdit(c *gin.Context) { } // GET /api/repos/:name -// @Summary Get repository info by name +// @Summary Get Repository Info // @Description Returns basic information about local repository. // @Tags Repos // @Produce json @@ -249,7 +249,7 @@ func apiReposShow(c *gin.Context) { c.JSON(200, repo) } -// @Summary Drop Repository +// @Summary Delete Repository // @Description Drop/delete a repo // @Description Cannot drop repos that are published. // @Description Needs force=1 to drop repos used as source by other repos. @@ -442,7 +442,7 @@ func apiReposPackagesDelete(c *gin.Context) { }) } -// @Summary Add packages from uploaded file +// @Summary Add Uploaded 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 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). @@ -462,7 +462,7 @@ func apiReposPackageFromFile(c *gin.Context) { apiReposPackageFromDir(c) } -// @Summary Add packages from uploaded directory +// @Summary Add 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). @@ -752,7 +752,7 @@ func apiReposCopyPackage(c *gin.Context) { }) } -// @Summary Include Packages from File Upload +// @Summary Include File from Directory // @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 @@ -780,7 +780,7 @@ type reposIncludePackageFromDirResponse struct { FailedFiles []string } -// @Summary Include Packages from Dir Upload +// @Summary Include Directory // @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 diff --git a/api/snapshot.go b/api/snapshot.go index d020c3dc..4af745e4 100644 --- a/api/snapshot.go +++ b/api/snapshot.go @@ -341,7 +341,7 @@ func apiSnapshotsUpdate(c *gin.Context) { }) } -// @Summary Get snapshot information +// @Summary Get Snapshot Info // @Description **Query detailed information about a snapshot by name** // @Tags Snapshots // @Param name path string true "Name of the snapshot" @@ -369,8 +369,8 @@ func apiSnapshotsShow(c *gin.Context) { c.JSON(200, snapshot) } -// @Summary Drop Snapshot -// @Description **Drop/delete snapshot by name** +// @Summary Delete Snapshot +// @Description **Delete snapshot by name** // @Description Cannot drop snapshots that are published. // @Description Needs force=1 to drop snapshots used as source by other snapshots. // @Tags Snapshots diff --git a/api/task.go b/api/task.go index 1d136325..1339f96a 100644 --- a/api/task.go +++ b/api/task.go @@ -7,7 +7,7 @@ import ( "github.com/gin-gonic/gin" ) -// @Summary Get tasks +// @Summary List Tasks // @Description **Get list of available tasks. Each task is returned as in “show” API** // @Tags Tasks // @Produce json @@ -18,7 +18,7 @@ func apiTasksList(c *gin.Context) { c.JSON(200, list.GetTasks()) } -// @Summary Clear finished and failed tasks +// @Summary Clear Tasks // @Description **Removes finished and failed tasks from internal task list** // @Tags Tasks // @Produce json @@ -30,7 +30,7 @@ func apiTasksClear(c *gin.Context) { c.JSON(200, gin.H{}) } -// @Summary Wait for task completion +// @Summary Wait for all Tasks // @Description **Waits for and returns when all running tasks are complete** // @Tags Tasks // @Produce json @@ -42,7 +42,7 @@ func apiTasksWait(c *gin.Context) { c.JSON(200, gin.H{}) } -// @Summary Wait for task to process +// @Summary Wait for Task // @Description **Waits for and returns when given Task ID is complete** // @Tags Tasks // @Produce json @@ -68,7 +68,7 @@ func apiTasksWaitForTaskByID(c *gin.Context) { c.JSON(200, task) } -// @Summary Return task information +// @Summary Get Task Info // @Description **Return task information for a given ID** // @Tags Tasks // @Produce plain @@ -95,7 +95,7 @@ func apiTasksShow(c *gin.Context) { c.JSON(200, task) } -// @Summary Return task output +// @Summary Get Task Output // @Description **Return task output for a given ID** // @Tags Tasks // @Produce plain @@ -122,7 +122,7 @@ func apiTasksOutputShow(c *gin.Context) { c.JSON(200, output) } -// @Summary Return task detail +// @Summary Get Task Details // @Description **Return task detail for a given ID** // @Tags Tasks // @Produce json @@ -149,7 +149,7 @@ func apiTasksDetailShow(c *gin.Context) { c.JSON(200, detail) } -// @Summary Return task return value (status code) +// @Summary Get Task Return Value // @Description **Return task return value (status code) by given ID** // @Tags Tasks // @Produce plain @@ -175,7 +175,7 @@ func apiTasksReturnValueShow(c *gin.Context) { c.JSON(200, output) } -// @Summary Delete task +// @Summary Delete Task // @Description **Delete completed task by given ID. Does not stop task execution** // @Tags Tasks // @Produce json