From b6673743256f2fdc8033f1c286e61d34b7269c0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Roth?= <neolynx@gmail.com>
Date: Fri, 4 Oct 2024 18:13:47 +0200
Subject: [PATCH] document apiPublishRemove

---
 api/publish.go | 57 +++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 42 insertions(+), 15 deletions(-)

diff --git a/api/publish.go b/api/publish.go
index 44839e21e..5fb8adb8a 100644
--- a/api/publish.go
+++ b/api/publish.go
@@ -15,12 +15,18 @@ import (
 
 // SigningOptions is a shared between publish API GPG options structure
 type SigningOptions struct {
-	Skip           bool
-	GpgKey         string
-	Keyring        string
-	SecretKeyring  string
-	Passphrase     string
-	PassphraseFile string
+	// Set "true" to skip signing published repository
+	Skip bool `           binding:"required"   json:"Skip"           example:"false"`
+	// key name (local to aptly service user)
+	GpgKey string `       binding:"required"   json:"GpgKey"         example:"reposign@aptly.info"`
+	// keyring filename (local to aptly service user)
+	Keyring string `      binding:"required"   json:"Keyring"        example:"trustedkeys.gpg"`
+	// OBSOLETE (gpg1): secret keyring filename (local to aptly server user)
+	SecretKeyring string `binding:"required"   json:"SecretKeyring"  example:"aptly.sec"`
+	// key passphrase (if using over http, would be transmitted in clear text!)
+	Passphrase string `                        json:"Passphrase"`
+	// passphrase file (local to aptly service user)
+	PassphraseFile string `                    json:"PassphraseFile" example:"/etc/aptly.pass"`
 }
 
 func getSigner(options *SigningOptions) (pgp.Signer, error) {
@@ -397,20 +403,41 @@ func apiPublishDrop(c *gin.Context) {
 	})
 }
 
-// POST /publish/:prefix/:distribution/remove
+type publishRemoveParams struct {
+	// Signing parameters
+	Signing SigningOptions `                 json:"Signing"`
+	// Do not remove unreferenced files in prefix/component
+	SkipCleanup *bool `                      json:"SkipCleanup"     example:"false"`
+	// List of Components
+	Components []string `binding:"required"  json:"Components"      example:"main"`
+	// Enable multiple packages with the same filename in different distributions
+	MultiDist bool `                         json:"MultiDist"       example:"false"`
+	// Overwrite existing files in pool/ directory
+	ForceOverwrite bool `                    json:"ForceOverwrite"  example:"false"`
+}
+
+// @Summary Remove sources
+// @Description **Remove sources (snapshots / local repos) from publish**
+// @Description
+// @Description This removes ...
+// @Tags Publish
+// @Param prefix path string true "Publishing prefix, `.` for root"
+// @Param distribution path string true "Distribution name"
+// @Consume json
+// @Param request body publishRemoveParams true "Parameters"
+// @Produce json
+// @Success 200 {object} task.ProcessReturnValue "Mirror was updated successfully"
+// @Success 202 {object} task.Task "Mirror is being updated"
+// @Failure 400 {object} Error "Unable to determine list of architectures"
+// @Failure 404 {object} Error "Mirror not found"
+// @Failure 500 {object} Error "Internal Error"
+// @Router /api/publish/{prefix}/{distributioni}/remove [post]
 func apiPublishRemove(c *gin.Context) {
 	param := parseEscapedPath(c.Params.ByName("prefix"))
 	storage, prefix := deb.ParsePrefix(param)
 	distribution := c.Params.ByName("distribution")
 
-	var b struct {
-		ForceOverwrite bool
-		Signing        SigningOptions
-		SkipCleanup    *bool
-		Components     []string `binding:"required"`
-		MultiDist      bool
-	}
-
+	var b publishRemoveParams
 	if c.Bind(&b) != nil {
 		return
 	}