diff --git a/api/files.go b/api/files.go index 64e3a527..9adf1d4b 100644 --- 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" diff --git a/api/repos.go b/api/repos.go index bf540c52..413a49e0 100644 --- 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" diff --git a/api/snapshot.go b/api/snapshot.go index 75110f71..54433096 100644 --- 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" diff --git a/docs/Database.md b/docs/Database.md index 8786b3ff..96cde17d 100644 --- a/docs/Database.md +++ b/docs/Database.md @@ -1 +1,4 @@ # Aptly Database Operations +
+ +
diff --git a/docs/Files.md b/docs/Files.md new file mode 100644 index 00000000..b33f80da --- /dev/null +++ b/docs/Files.md @@ -0,0 +1,4 @@ +# File Operations +
+ +
diff --git a/docs/GPG.md b/docs/GPG.md new file mode 100644 index 00000000..c33bf937 --- /dev/null +++ b/docs/GPG.md @@ -0,0 +1,4 @@ +# GPG Keys +
+ +
diff --git a/docs/Graph.md b/docs/Graph.md new file mode 100644 index 00000000..25e2a2df --- /dev/null +++ b/docs/Graph.md @@ -0,0 +1,4 @@ +# Dependency Graph +
+ +
diff --git a/docs/Mirrors.md b/docs/Mirrors.md new file mode 100644 index 00000000..160cf3c4 --- /dev/null +++ b/docs/Mirrors.md @@ -0,0 +1,5 @@ +# Repository Mirrors +
+ +
+ diff --git a/docs/Packages.md b/docs/Packages.md new file mode 100644 index 00000000..694061b4 --- /dev/null +++ b/docs/Packages.md @@ -0,0 +1,5 @@ +# Packages +
+ +
+ diff --git a/docs/Publish.md b/docs/Publish.md index b99a2cc8..44d5fdb1 100644 --- a/docs/Publish.md +++ b/docs/Publish.md @@ -1,10 +1,7 @@ # Aptly Publish Points
-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 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 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.
diff --git a/docs/Repos.md b/docs/Repos.md new file mode 100644 index 00000000..3a756365 --- /dev/null +++ b/docs/Repos.md @@ -0,0 +1,5 @@ +# Repositories +
+ +
+ diff --git a/docs/S3.md b/docs/S3.md new file mode 100644 index 00000000..d5c31088 --- /dev/null +++ b/docs/S3.md @@ -0,0 +1,5 @@ +# S3 Endpoints +
+ +
+ diff --git a/docs/Snapshots.md b/docs/Snapshots.md new file mode 100644 index 00000000..c02b668e --- /dev/null +++ b/docs/Snapshots.md @@ -0,0 +1,9 @@ +# Repository and Mirror Snapshots +
+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) +
diff --git a/docs/Tasks.md b/docs/Tasks.md new file mode 100644 index 00000000..2dbf8072 --- /dev/null +++ b/docs/Tasks.md @@ -0,0 +1,4 @@ +# Background Tasks +
+ +
diff --git a/docs/api.md b/docs/api.md index 9d236ce2..8618e2d7 100644 --- 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 diff --git a/docs/docs.html b/docs/docs.html index cb405d9b..35eb3c9b 100644 --- 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 */ diff --git a/docs/swagger.conf.tpl b/docs/swagger.conf.tpl index 670470b9..e846c570 100644 --- 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: