From 467991e8ba03e0937edaba788d68f80d06e4110e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Roth?= <neolynx@gmail.com>
Date: Tue, 11 Jun 2024 18:51:38 +0200
Subject: [PATCH] swagger: document mirror api

---
 api/mirror.go | 65 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 4 deletions(-)

diff --git a/api/mirror.go b/api/mirror.go
index e5ae905bf..3b3d721f5 100644
--- a/api/mirror.go
+++ b/api/mirror.go
@@ -154,7 +154,18 @@ func apiMirrorsCreate(c *gin.Context) {
 	c.JSON(201, repo)
 }
 
-// DELETE /api/mirrors/:name
+// @Summary Delete Mirror
+// @Description Delete a mirror
+// @Tags Mirrors
+// @Consume  json
+// @Produce  json
+// @Param name path string true "mirror name"
+// @Param force query int true "force: 1 to enable"
+// @Success 200 {object} task.ProcessReturnValue
+// @Failure 404 {object} Error "Mirror not found"
+// @Failure 403 {object} Error "Unable to delete mirror with snapshots"
+// @Failure 500 {object} Error "Unable to delete"
+// @Router /api/mirrors/{name} [delete]
 func apiMirrorsDrop(c *gin.Context) {
 	name := c.Params.ByName("name")
 	force := c.Request.URL.Query().Get("force") == "1"
@@ -193,7 +204,16 @@ func apiMirrorsDrop(c *gin.Context) {
 	})
 }
 
-// GET /api/mirrors/:name
+// @Summary Show Mirror
+// @Description Get mirror information by name
+// @Tags Mirrors
+// @Consume  json
+// @Produce  json
+// @Param name path string true "mirror name"
+// @Success 200 {object} deb.RemoteRepo
+// @Failure 404 {object} Error "Mirror not found"
+// @Failure 500 {object} Error "Internal Error"
+// @Router /api/mirrors/{name} [get]
 func apiMirrorsShow(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
 	collection := collectionFactory.RemoteRepoCollection()
@@ -213,7 +233,19 @@ func apiMirrorsShow(c *gin.Context) {
 	c.JSON(200, repo)
 }
 
-// GET /api/mirrors/:name/packages
+// @Summary List Mirror Packages
+// @Description Get a list of packages from a mirror
+// @Tags Mirrors
+// @Consume  json
+// @Produce  json
+// @Param name path string true "mirror name"
+// @Param q query string false "search query"
+// @Param format query string false "format: `details` for more detailed information"
+// @Success 200 {array} deb.Package "List of Packages"
+// @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/mirrors/{name}/packages [get]
 func apiMirrorsPackages(c *gin.Context) {
 	collectionFactory := context.NewCollectionFactory()
 	collection := collectionFactory.RemoteRepoCollection()
@@ -291,7 +323,32 @@ func apiMirrorsPackages(c *gin.Context) {
 	}
 }
 
-// PUT /api/mirrors/:name
+// @Summary Update Mirror
+// @Description Update Mirror and download packages
+// @Tags Mirrors
+// @Consume  json
+// @Produce  json
+// @Param name path string true "mirror name to update"
+// @Param Name query string false "change mirror name"
+// @Param ArchiveURL query string false "ArchiveURL"
+// @Param Filter query string false "Filter"
+// @Param Architectures query []string false "Architectures"
+// @Param Components query []string false "Components"
+// @Param Keyrings query []string false "Keyrings"
+// @Param FilterWithDeps query bool false "FilterWithDeps"
+// @Param DownloadSources query bool false "DownloadSources"
+// @Param DownloadUdebs query bool false "DownloadUdebs"
+// @Param SkipComponentCheck query bool false "SkipComponentCheck"
+// @Param IgnoreChecksums query bool false "IgnoreChecksums"
+// @Param IgnoreSignatures query bool false "IgnoreSignatures"
+// @Param ForceUpdate query bool false "ForceUpdate"
+// @Param SkipExistingPackages query bool false "SkipExistingPackages"
+// @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/mirrors/{name} [put]
 func apiMirrorsUpdate(c *gin.Context) {
 	var (
 		err    error