update

2026-01-11 03:11:50 +00:00 · 2024-11-02 18:09:43 +01:00
parent c055611914
commit 8f8de4bd29
17 changed files with 107 additions and 86 deletions
--- a/api/files.go
+++ b/api/files.go
@@ -67,10 +67,13 @@ func apiFilesListDirs(c *gin.Context) {
 	c.JSON(200, list)
 }

-// @Summary TODO
-// @Description **ToDo**
+// @Summary Upload file glaa
+// @Description **Upload a file to a directory**
 // @Description To Do
 // @Tags Files
+// @Accept multipart/form-data
+// @Param dir path string true "Directory to upload files to"
+// @Param files formData file true "Files to upload"
 // @Produce json
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
--- a/api/repos.go
+++ b/api/repos.go
@@ -399,10 +399,13 @@ func apiReposPackagesDelete(c *gin.Context) {
 	})
 }

-// @Summary TODO
-// @Description **ToDo**
+// @Summary Add packages
+// @Description **Add package file**
 // @Description To Do
 // @Tags Repos
+// @Param name path string true "Repository name"
+// @Param dir path string true "Directory of packages"
+// @Param file path string false "Filename (optional)"
 // @Produce json
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
@@ -427,7 +430,7 @@ func apiReposPackageFromFile(c *gin.Context) {
 // @Failure 400 {object} Error "wrong file"
 // @Failure 404 {object} Error "Repository not found"
 // @Failure 500 {object} Error "Error adding files"
-// @Router /api/repos/{name}/{dir} [post]
+// @Router /api/repos/{name}/file/{dir} [post]
 func apiReposPackageFromDir(c *gin.Context) {
 	forceReplace := c.Request.URL.Query().Get("forceReplace") == "1"
 	noRemove := c.Request.URL.Query().Get("noRemove") == "1"
--- a/api/snapshot.go
+++ b/api/snapshot.go
@@ -187,10 +187,18 @@ func apiSnapshotsCreate(c *gin.Context) {
 	})
 }

-// @Summary TODO
-// @Description **ToDo**
+type snapshotRepositoryParams  struct {
+        Name        string `binding:"required"`
+        Description string
+}
+
+// @Summary Snapshot Repository
+// @Description **Create a sbalshot of a repository**
 // @Description To Do
 // @Tags Snapshots
+// @Param name path string true "Repository name"
+// @Consume json
+// @Param request body snapshotRepositoryParams true "Parameters"
 // @Produce json
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
@@ -200,13 +208,9 @@ func apiSnapshotsCreateFromRepository(c *gin.Context) {
 		err      error
 		repo     *deb.LocalRepo
 		snapshot *deb.Snapshot
+                b        snapshotRepositoryParams
 	)

-	var b struct {
-		Name        string `binding:"required"`
-		Description string
-	}
-
 	if c.Bind(&b) != nil {
 		return
 	}
@@ -305,10 +309,11 @@ func apiSnapshotsUpdate(c *gin.Context) {
 	})
 }

-// @Summary TODO
-// @Description **ToDo**
+// @Summary Get snapshot information
+// @Description **Get information about a snapshot**
 // @Description To Do
 // @Tags Snapshots
+// @Param name path string true "Name of the snapshot"
 // @Produce json
 // @Success 200 {object} string "msg"
 // @Failure 404 {object} Error "Not Found"
--- a/docs/Database.md
+++ b/docs/Database.md
@@ -1 +1,4 @@
 # Aptly Database Operations
+<div>
+
+</div>
--- a/docs/Files.md
+++ b/docs/Files.md
@@ -0,0 +1,4 @@
+# File Operations
+<div>
+
+</div>
--- a/docs/GPG.md
+++ b/docs/GPG.md
@@ -0,0 +1,4 @@
+# GPG Keys
+<div>
+
+</div>
--- a/docs/Graph.md
+++ b/docs/Graph.md
@@ -0,0 +1,4 @@
+# Dependency Graph
+<div>
+
+</div>
--- a/docs/Mirrors.md
+++ b/docs/Mirrors.md
@@ -0,0 +1,5 @@
+# Repository Mirrors
+<div>
+
+</div>
+
--- a/docs/Packages.md
+++ b/docs/Packages.md
@@ -0,0 +1,5 @@
+# Packages
+<div>
+
+</div>
+
--- a/docs/Publish.md
+++ b/docs/Publish.md
@@ -1,10 +1,7 @@
 # Aptly Publish Points
 <div>

-Publish snapshot or local repo as Debian repository which could be
-served by HTTP/FTP/rsync server. Repository is signed by user's key with
-GnuPG. Key should be created beforehand (see section GPG Keys below).
-Published repository could be consumed directly by apt.
+Publish snapshot or local repo as Debian repository which could be served by HTTP/FTP/rsync server. Repository is signed by user's key with GnuPG. Key should be created beforehand (see section GPG Keys below).  Published repository could be consumed directly by apt.

 Repositories could be published to Amazon S3 service: create bucket,
 [configure publishing endpoint](/doc/feature/s3/) and use S3 endpoint when
@@ -13,25 +10,17 @@ publishing.

 #### GPG Keys

-GPG key is required to sign any published repository. Key should be
-generated before publishing first repository.
+GPG key is required to sign any published repository. Key should be generated before publishing first repository.

-Key generation, storage, backup and revocation is out of scope of this
-document, there are many tutorials available, e.g. [this one](http://fedoraproject.org/wiki/Creating_GPG_Keys).
+Key generation, storage, backup and revocation is out of scope of this document, there are many tutorials available, e.g. [this one](http://fedoraproject.org/wiki/Creating_GPG_Keys).

-Publiс part of the key should be exported from your keyring using `gpg --export --armor` and
-imported into apt keyring using `apt-key` tool on all machines that would be using published
-repositories.
+Publiс part of the key should be exported from your keyring using `gpg --export --armor` and imported into apt keyring using `apt-key` tool on all machines that would be using published repositories.

-Signing releases is highly recommended, but if you want to skip it, you
-can either use `gpgDisableSign` configuration option or `--skip-signing`
-flag.
+Signing releases is highly recommended, but if you want to skip it, you can either use `gpgDisableSign` configuration option or `--skip-signing` flag.

 #### Parameters

-Publish APIs use following convention to identify published repositories: `/api/publish/:prefix/:distribution`.
-`:distribution` is distribution name, while `:prefix` is `[<storage>:]<prefix>` (storage is optional, it defaults
-to empty string), if publishing prefix contains slashes `/`, they should be replaced with underscores (`_`) and underscores
+Publish APIs use following convention to identify published repositories: `/api/publish/:prefix/:distribution`.  `:distribution` is distribution name, while `:prefix` is `[<storage>:]<prefix>` (storage is optional, it defaults to empty string), if publishing prefix contains slashes `/`, they should be replaced with underscores (`_`) and underscores
 should be replaced with double underscore (`__`). To specify root `:prefix`, use `:.`, as `.` is ambigious in URLs.

 </div>
--- a/docs/Repos.md
+++ b/docs/Repos.md
@@ -0,0 +1,5 @@
+# Repositories
+<div>
+
+</div>
+
--- a/docs/S3.md
+++ b/docs/S3.md
@@ -0,0 +1,5 @@
+# S3 Endpoints
+<div>
+
+</div>
+
--- a/docs/Snapshots.md
+++ b/docs/Snapshots.md
@@ -0,0 +1,9 @@
+# Repository and Mirror Snapshots
+<div>
+Snapshot is a fixed state of remote repository mirror or local repository. Internally snapshot is list of references to packages.
+Snapshot is immutable, i.e. it can't be changed since it has been created. Snapshots could be [merged](/doc/aptly/snapshot/merge/),
+[filtered](/doc/aptly/snapshot/pull/),
+individual packages could be [pulled](/doc/aptly/snapshot/pull/), snapshot could be
+[verified](/doc/aptly/snapshot/verify/) for missing dependencies. Finally, snapshots could be
+[published as repositories](/doc/aptly/publish/snapshot)
+</div>
--- a/docs/Tasks.md
+++ b/docs/Tasks.md
@@ -0,0 +1,4 @@
+# Background Tasks
+<div>
+
+</div>
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,4 +1,3 @@
-
 Using aptly via REST API allows to achieve two goals:

 1. Remote access to aptly service: e.g. uploading packages and publishing them from CI server.
@@ -59,54 +58,3 @@ Aptly's HTTP API shouldn't be directly exposed to the Internet: there's no authe
 1. GPG key passphrase can't be input on console, so either passwordless GPG keys are required or passphrase should be specified in API parameters.
 1. Some script might be required to start/stop aptly HTTP service.
 1. Some parameters are given as part of URLs, which requires proper url encoding. Unfortunately, at the moment it's not possible to pass URL arguments with `/` in them.
-
-### How to implement equivalent of aptly commands using API
-
-* `aptly mirror`: [mirror API](/doc/api/mirror)
-    * `list`: list
-    * `create`: create
-    * `drop`: delete
-    * `show`: show
-    * `search`: show packages/search
-    * `update`: update mirror
-* `aptly repo`: [local repos API](/doc/api/repos)
-    * `add`: [file upload API](/doc/api/files) + add packages from uploaded file
-    * `copy`: show packages/search + add packages by key
-    * `create`: create
-    * `drop`: delete
-    * `edit`: edit
-    * `import`: not available, as mirror API is not implemented yet
-    * `list`: list
-    * `move`: show packages/search + add packages by key + delete packages by key
-    * `remove`: show packages/search + delete packages by key
-    * `rename`: not available yet, should be part of edit API
-    * `search`: show packages/search
-    * `show`: show
-* `aptly snapshot`: [snapshots API](/doc/api/snapshots)
-    * `create`:
-        * empty: create snapshot with empty package references
-        * from mirror: not available yet
-        * from local repo: create snapshot from local repo
-    * `diff`: snapshot difference API
-    * `drop`: delete
-    * `filter`: show packages/search + create snapshot from package references
-    * `list`: list
-    * `merge`: show packages/search + processing + create snapshot from package references
-    * `pull`: show packages/search + processing + create snapshot from package references (might be implemented as API in future versions)
-    * `rename`: edit
-    * `search`: show packages/search
-    * `show`: show
-    * `verify`: not available yet
-* `aptly publish`: [publish API](/doc/api/publish)
-    * `drop`: delete
-    * `list`: list
-    * `repo`: publish repo
-    * `snapshot`: publish snapshot
-    * `switch`: switch/update
-    * `update`: switch/update
-* `aptly package`: [packages API](/doc/api/packages)
-    * `search`: not available yet
-    * `show`: only one format, with package key as input
-* `aptly graph`: [graph API](/doc/api/misc)
-* `aptly version`: [version API](/doc/api/misc)
-* `aptly db`: not available yet
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -36,7 +36,7 @@
        margin-left: auto !important;
        margin-right: 2em;
        font-weight: bold;
-        font-size: 14pt !important;
+        font-size: 16pt !important;
    }

    /* Tag Group */
@@ -47,9 +47,16 @@
        width: 7em;
    }

-    /* */
+    /* Group Heading */
    .swagger-ui .opblock-tag-section .opblock-tag .markdown > h1 {
-        font-size: 16pt;
+        font-size: 14pt;
+        margin-top: 0px;
+        margin-left: 1em;
+    }
+
+    /* Group Description */
+    .swagger-ui .opblock-tag-section .opblock-tag .markdown > div {
+        font-size: 12pt;
    }

    /* Show Tag Group description only if opened */
--- a/docs/swagger.conf.tpl
+++ b/docs/swagger.conf.tpl
@@ -6,11 +6,29 @@ package docs
 // @contact.name   Aptly
 // @contact.url    http://github.com/aptly-dev/aptly

+// @Tag.name Repos
+// @Tag.description.markdown
+// @Tag.name Files
+// @Tag.description.markdown
+// @Tag.name Packages
+// @Tag.description.markdown
+// @Tag.name Mirrors
+// @Tag.description.markdown
+// @Tag.name Snapshots
+// @Tag.description.markdown
 // @Tag.name Publish
 // @Tag.description.markdown
+// @Tag.name Graph
+// @Tag.description.markdown
+// @Tag.name S3
+// @Tag.description.markdown
+// @Tag.name GPG
+// @Tag.description.markdown
 // @Tag.name Database
 // @Tag.description.markdown
 // @Tag.name Status
 // @Tag.description.markdown
+// @Tag.name Tasks
+// @Tag.description.markdown

 // version will be appended here: