update doc

api/gpg.go

@@ -19,9 +19,11 @@ type gpgAddKeyParams struct {
 	Keyring     string
 }
 
-// @Summary Add GPG Key
-// @Description Adds a GPG key to aptly keyring
-// @Tags GPG
+// @Summary Add GPG Keys
+// @Description **Adds GPG keys to aptly keyring**
+// @Description
+// @Description Add GPG public keys for veryfing remote repositories for mirroring.
+// @Tags Mirrors
 // @Produce json
 // @Success 200 {object} string "OK"
 // @Failure 400 {object} Error "Bad Request"

api/graph.go

@@ -13,17 +13,26 @@ import (
 )
 
 // @Summary Graph Output
-// @Description **Generate graph of aptly objects (same as in aptly graph command).**
-// @Description e.g open url `http://localhost:8080/api/graph.svg?layout=vertical` in browser
-// @Tags Graph
+// @Description **Generate dependency graph**
+// @Description
+// @Description Command graph generates graph of dependencies:
+// @Description
+// @Description * between snapshots and mirrors (what mirror was used to create each snapshot)
+// @Description * between snapshots and local repos (what local repo was used to create snapshot)
+// @Description * between snapshots (pulling, merging, etc.)
+// @Description * between snapshots, local repos and published repositories (how snapshots were published).
+// @Description
+// @Description Graph is rendered to PNG file using graphviz package.
+// @Description
+// @Description Example URL: `http://localhost:8080/api/graph.svg?layout=vertical`
+// @Tags Status
 // @Produce json
 // @Param ext path string true "ext specifies desired file extension, e.g. .png, .svg."
 // @Param layout query string false "Change between a `horizontal` (default) and a `vertical` graph layout."
 // @Success 200 {object} []byte "Output"
 // @Failure 404 {object} Error "Not Found"
 // @Failure 500 {object} Error "Internal Server Error"
-// @Router /api/graph [get]
-// GET /api/graph.:ext?layout=[vertical|horizontal(default)]
+// @Router /api/graph.{ext} [get]
 func apiGraph(c *gin.Context) {
 	var (
 		err    error

api/mirror.go

@@ -31,7 +31,7 @@ func getVerifier(keyRings []string) (pgp.Verifier, error) {
 	return verifier, nil
 }
 
-// @Summary Get mirrors
+// @Summary Get Mirrors
 // @Description **Show list of currently available mirrors**
 // @Description Each mirror is returned as in “show” API.
 // @Tags Mirrors
@@ -82,8 +82,8 @@ type mirrorCreateParams struct {
 	IgnoreSignatures bool `                  json:"IgnoreSignatures"`
 }
 
-// @Summary Create mirror
-// @Description **Create a mirror**
+// @Summary Create Mirror
+// @Description **Create a mirror of a remote repositoru**
 // @Tags Mirrors
 // @Consume json
 // @Param request body mirrorCreateParams true "Parameters"

api/s3.go

@@ -6,8 +6,10 @@ import (
 
 // @Summary S3 buckets
 // @Description **Get list of S3 buckets**
-// @Tags S3
-// @Produce  json
+// @Description
+// @Description List configured S3 buckets.
+// @Tags Status
+// @Produce json
 // @Success 200 {array} string "List of S3 buckets"
 // @Router /api/s3 [get]
 func apiS3List(c *gin.Context) {

api/storage.go

@@ -18,6 +18,8 @@ type diskFree struct {
 
 // @Summary Get Storage Utilization
 // @Description **Get disk free information of aptly storage**
+// @Description
+// @Description Units in MiB.
 // @Tags Status
 // @Produce json
 // @Success 200 {object} diskFree "Storage information"