From ad4d0c7b96a575da11600f435a1dad87e8470aeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Roth?= Date: Sun, 8 Jun 2025 14:24:27 +0200 Subject: [PATCH] doc: add swagger doc for /api/gpg/key - cleanup swagger validation errors --- api/gpg.go | 24 ++++++++++++++++-------- api/repos.go | 37 ++++++++++++++++++++++++------------- 2 files changed, 40 insertions(+), 21 deletions(-) diff --git a/api/gpg.go b/api/gpg.go index 94891e93..47ba1d92 100644 --- a/api/gpg.go +++ b/api/gpg.go @@ -13,26 +13,34 @@ import ( ) type gpgAddKeyParams struct { - // Keyserver, when downloading GpgKeyIDs - Keyserver string `json:"Keyserver" example:"hkp://keyserver.ubuntu.com:80"` - // GpgKeyIDs to download from Keyserver, comma separated list - GpgKeyID string `json:"GpgKeyID" example:"EF0F382A1A7B6500,8B48AD6246925553"` - // Armored gpg public ket, instead of downloading from keyserver - GpgKeyArmor string `json:"GpgKeyArmor" example:""` // Keyring for adding the keys (default: trustedkeys.gpg) Keyring string `json:"Keyring" example:"trustedkeys.gpg"` + + // Add ASCII armored gpg public key, do not download from keyserver + GpgKeyArmor string `json:"GpgKeyArmor" example:""` + + // Keyserver to download keys provided in `GpgKeyID` + Keyserver string `json:"Keyserver" example:"hkp://keyserver.ubuntu.com:80"` + // Keys do download from `Keyserver`, separated by space + GpgKeyID string `json:"GpgKeyID" example:"EF0F382A1A7B6500 8B48AD6246925553"` } // @Summary Add GPG Keys // @Description **Adds GPG keys to aptly keyring** // @Description // @Description Add GPG public keys for veryfing remote repositories for mirroring. +// @Description +// @Description Keys can be added in two ways: +// @Description * By providing the ASCII armord key in `GpgKeyArmor` (leave Keyserver and GpgKeyID empty) +// @Description * By providing a `Keyserver` and one or more key IDs in `GpgKeyID`, separated by space (leave GpgKeyArmor empty) +// @Description // @Tags Mirrors +// @Consume json +// @Param request body gpgAddKeyParams true "Parameters" // @Produce json // @Success 200 {object} string "OK" // @Failure 400 {object} Error "Bad Request" -// @Failure 404 {object} Error "Not Found" -// @Router /api/gpg [post] +// @Router /api/gpg/key [post] func apiGPGAddKey(c *gin.Context) { b := gpgAddKeyParams{} if c.Bind(&b) != nil { diff --git a/api/repos.go b/api/repos.go index dcd701d1..0ced5efd 100644 --- a/api/repos.go +++ b/api/repos.go @@ -107,9 +107,9 @@ type repoCreateParams struct { // @Description {"Name":"aptly-repo","Comment":"","DefaultDistribution":"","DefaultComponent":""} // @Description ``` // @Tags Repos -// @Produce json // @Consume json // @Param request body repoCreateParams true "Parameters" +// @Produce json // @Success 201 {object} deb.LocalRepo // @Failure 404 {object} Error "Source snapshot not found" // @Failure 409 {object} Error "Local repo already exists" @@ -178,8 +178,10 @@ type reposEditParams struct { // @Summary Update Repository // @Description **Update local repository meta information** // @Tags Repos -// @Produce json +// @Param name path string true "Repository name" +// @Consume json // @Param request body reposEditParams true "Parameters" +// @Produce json // @Success 200 {object} deb.LocalRepo "msg" // @Failure 404 {object} Error "Not Found" // @Failure 500 {object} Error "Internal Server Error" @@ -231,8 +233,8 @@ func apiReposEdit(c *gin.Context) { // @Summary Get Repository Info // @Description Returns basic information about local repository. // @Tags Repos -// @Produce json // @Param name path string true "Repository name" +// @Produce json // @Success 200 {object} deb.LocalRepo // @Failure 404 {object} Error "Repository not found" // @Router /api/repos/{name} [get] @@ -254,9 +256,10 @@ func apiReposShow(c *gin.Context) { // @Description Cannot drop repos that are published. // @Description Needs force=1 to drop repos used as source by other repos. // @Tags Repos -// @Produce json +// @Param name path string true "Repository name" // @Param _async query bool false "Run in background and return task object" // @Param force query int false "force: 1 to enable" +// @Produce json // @Success 200 {object} task.ProcessReturnValue "Repo object" // @Failure 404 {object} Error "Not Found" // @Failure 404 {object} Error "Repo Conflict" @@ -306,12 +309,12 @@ func apiReposDrop(c *gin.Context) { // @Description ["Pi386 aptly 0.8 966561016b44ed80"] // @Description ``` // @Tags Repos -// @Produce json -// @Param name path string true "Snapshot to search" +// @Param name path string true "Repository name" // @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" +// @Produce json // @Success 200 {object} string "msg" // @Failure 404 {object} Error "Not Found" // @Failure 404 {object} Error "Internal Server Error" @@ -406,9 +409,10 @@ func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(li // @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 name path string true "Repository name" // @Param request body reposPackagesAddDeleteParams true "Parameters" // @Param _async query bool false "Run in background and return task object" +// @Produce json // @Success 200 {object} string "msg" // @Failure 400 {object} Error "Bad Request" // @Failure 404 {object} Error "Not Found" @@ -426,9 +430,11 @@ func apiReposPackagesAdd(c *gin.Context) { // @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 name path string true "Repository name" // @Param _async query bool false "Run in background and return task object" +// @Consume json +// @Param request body reposPackagesAddDeleteParams true "Parameters" +// @Produce json // @Success 200 {object} string "msg" // @Failure 400 {object} Error "Bad Request" // @Failure 404 {object} Error "Not Found" @@ -608,8 +614,8 @@ type reposCopyPackageParams struct { // @Description Copies a package from a source to destination repository // @Tags Repos // @Produce json -// @Param name path string true "Source repo" -// @Param src path string true "Destination repo" +// @Param name path string true "Destination repo" +// @Param src path string true "Source repo" // @Param file path string true "File/packages to copy" // @Param _async query bool false "Run in background and return task object" // @Success 200 {object} task.ProcessReturnValue "msg" @@ -762,12 +768,15 @@ func apiReposCopyPackage(c *gin.Context) { // @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 +// @Param name path string true "Repository name" +// @Param dir path string true "Directory of packages" +// @Param file path string true "File/packages to include" // @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 in background and return task object" +// @Produce json // @Success 200 {object} string "msg" // @Failure 404 {object} Error "Not Found" // @Router /api/repos/{name}/include/{dir}/{file} [post] @@ -784,12 +793,14 @@ type reposIncludePackageFromDirResponse struct { // @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 +// @Param name path string true "Repository name" +// @Param dir path string true "Directory of packages" // @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 in background and return task object" +// @Produce json // @Success 200 {object} reposIncludePackageFromDirResponse "Response" // @Failure 404 {object} Error "Not Found" // @Router /api/repos/{name}/include/{dir} [post]