From c6e0a06b141ae2d0ded33da0eb014409e6e3a1eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Roth?= <neolynx@gmail.com>
Date: Thu, 28 Nov 2024 15:51:18 +0100
Subject: [PATCH] swagger: cleanup

---
 api/api.go     |  7 ++++++-
 api/publish.go |  6 ++++++
 api/repos.go   | 15 ++++++++++++++-
 docs/api.md    | 25 ++-----------------------
 4 files changed, 28 insertions(+), 25 deletions(-)

diff --git a/api/api.go b/api/api.go
index c66a44b1..adeef9d9 100644
--- a/api/api.go
+++ b/api/api.go
@@ -30,7 +30,12 @@ type aptlyVersion struct {
 
 // @Summary Aptly version
 // @Description **Get aptly version**
-// @Description Returns the aptly version
+// @Description
+// @Description **Example:**
+// @Description ```
+// @Description $ curl http://localhost:8080/api/version
+// @Description {"Version":"0.9~dev"}
+// @Description ```
 // @Tags Status
 // @Produce json
 // @Success 200 {object} aptlyVersion
diff --git a/api/publish.go b/api/publish.go
index 9b10e65f..9303b382 100644
--- a/api/publish.go
+++ b/api/publish.go
@@ -179,6 +179,12 @@ type publishedRepoCreateParams struct {
 // @Description
 // @Description The prefix may contain a storage specifier, e.g. `s3:packages/`, or it may also be empty to publish to the root directory.
 // @Description
+// @Description **Example:**
+// @Description ```
+// @Description $ curl -X POST -H 'Content-Type: application/json' --data '{"Distribution": "wheezy", "Sources": [{"Name": "aptly-repo"}]}' http://localhost:8080/api/publish//repos
+// @Description {"Architectures":["i386"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":".","SourceKind":"local","Sources":[{"Component":"main","Name":"aptly-repo"}],"Storage":""}
+// @Description ```
+// @Description
 // @Description See also: `aptly publish create`
 // @Tags Publish
 // @Param prefix path string true "publishing prefix"
diff --git a/api/repos.go b/api/repos.go
index fa6c3e17..93475337 100644
--- a/api/repos.go
+++ b/api/repos.go
@@ -98,8 +98,14 @@ type repoCreateParams struct {
 }
 
 // @Summary Create repository
-// @Description Create a local repository with specified parameters.
+// @Description **Create a local repository**
+// @Description
 // @Description Distribution and component are used as defaults when publishing repo either directly or via snapshot.
+// @Description
+// @Description ```
+// @Description $ curl -X POST -H 'Content-Type: application/json' --data '{"Name": "aptly-repo"}' http://localhost:8080/api/repos
+// @Description {"Name":"aptly-repo","Comment":"","DefaultDistribution":"","DefaultComponent":""}
+// @Description ```
 // @Tags Repos
 // @Produce  json
 // @Consume  json
@@ -287,7 +293,14 @@ func apiReposDrop(c *gin.Context) {
 
 // @Summary List Repo Packages
 // @Description **Return a list of packages present in the repo**
+// @Description
 // @Description If `q` query parameter is missing, return all packages, otherwise return packages that match q
+// @Description
+// @Description **Example:**
+// @Description ```
+// @Description $ curl http://localhost:8080/api/repos/aptly-repo/packages
+// @Description ["Pi386 aptly 0.8 966561016b44ed80"]
+// @Description ```
 // @Tags Repos
 // @Produce json
 // @Param name path string true "Snapshot to search"
diff --git a/docs/api.md b/docs/api.md
index 36dc761d..aaf87195 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -2,29 +2,8 @@ Aptly operations are also available via REST API served with `aptly api serve`.
 
 On Debian based systems, a package `aptly-api` is available, which will run aptly as systemd service as dedicated aptly-api user.
 
-#### Example API calls
+Some configuration changes (S3 publishing endpoints, ...) will require restarting the aptly service in order to take effect.
 
-    $ curl http://localhost:8080/api/version
-    {"Version":"0.9~dev"}
-
-    $ curl -F file=@aptly_0.8_i386.deb http://localhost:8080/api/files/aptly_0.8
-    ["aptly_0.8/aptly_0.8_i386.deb"]
-
-    $ curl -X POST -H 'Content-Type: application/json' --data '{"Name": "aptly-repo"}' http://localhost:8080/api/repos
-    {"Name":"aptly-repo","Comment":"","DefaultDistribution":"","DefaultComponent":""}
-
-    $ curl -X POST http://localhost:8080/api/repos/aptly-repo/file/aptly_0.8
-    {"failedFiles":[],"report":{"warnings":[],"added":["aptly_0.8_i386 added"],"removed":[]}}
-
-    $ curl http://localhost:8080/api/repos/aptly-repo/packages
-    ["Pi386 aptly 0.8 966561016b44ed80"]
-
-    $ curl -X POST -H 'Content-Type: application/json' --data '{"Distribution": "wheezy", "Sources": [{"Name": "aptly-repo"}]}' http://localhost:8080/api/publish//repos
-    {"Architectures":["i386"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":".","SourceKind":"local","Sources":[{"Component":"main","Name":"aptly-repo"}],"Storage":""}
-
-#### Notes
-
-- Some configuration changes (S3 publishing endpoints, ...) will require restarting the aptly service
-- Aptly's HTTP API shouldn't be directly exposed to the Internet as there is no authentication/protection of APIs. Consider using a HTTP proxy or server (e.g. nginx) to add an authentication mechanism.
+The REST API shouldn't be exposed to the Internet as there is no authentication/protection, consider using a HTTP proxy (e.g. nginx) to add https and authentication.
 
 #### Aptly REST API Documentation