vincent/aptly
1
0
Fork 0
mirror of https://github.com/aptly-dev/aptly.git synced 2026-01-12 03:21:33 +00:00
Code Issues Projects Releases Wiki Activity

add swagger documentation

Browse Source
This commit is contained in:
André Roth
2024-09-30 21:31:12 +02:00
parent 1d1bd41bb8
commit fb538333fa
8 changed files with 169 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
api/files.go
View File

@@ -33,7 +33,12 @@ func verifyDir(c *gin.Context) bool {
return true
}
// GET /files
// @Summary Get files
// @Description Get list of uploaded files.
// @Tags Files
// @Produce json
// @Success 200 {array} string "List of files"
// @Router /api/files [get]
func apiFilesListDirs(c *gin.Context) {
list := []string{}
listLock := &sync.Mutex{}

94
api/mirror.go
View File

@@ -31,7 +31,12 @@ func getVerifier(keyRings []string) (pgp.Verifier, error) {
return verifier, nil
}
// GET /api/mirrors
// @Summary Get mirrors
// @Description Show list of currently available mirrors. Each mirror is returned as in “show” API.
// @Tags Mirrors
// @Produce json
// @Success 200 {array} deb.RemoteRepo
// @Router /api/mirrors [get]
func apiMirrorsList(c *gin.Context) {
collectionFactory := context.NewCollectionFactory()
collection := collectionFactory.RemoteRepoCollection()
@@ -45,7 +50,27 @@ func apiMirrorsList(c *gin.Context) {
c.JSON(200, result)
}
// POST /api/mirrors
// @Summary Create mirror
// @Description Create empty mirror with specified parameters.
// @Tags Mirrors
// @Accept json
// @Produce json
// @Param Name query string true "mirror name"
// @Param ArchiveURL query string true "url of the archive to mirror e.g. http://deb.debian.org/debian/"
// @Param Distribution query string false "distribution name to mirror e.g. `buster`, for flat repositories use `./` instead of distribution name"
// @Param Filter query string false "package query that is applied to packages in the mirror"
// @Param Components query []string false "components to mirror, if not specified aptly would fetch all components"
// @Param Architectures query []string false "limit mirror to those architectures, if not specified aptly would fetch all architectures"
// @Param Keyrings query []string false "gpg keyring(s) to use when verifying `Release` file"
// @Param DownloadSources query bool false "whether to mirror sources"
// @Param DownloadUdebs query bool false "whether to mirror `.udeb` packages (Debian installer support)"
// @Param DownloadInstaller query bool false "whether to download additional not packaged installer files"
// @Param FilterWithDeps query bool false "when filtering, include dependencies of matching packages as well"
// @Param SkipComponentCheck query bool false "whether to skip if the given components are in the `Release` file"
// @Param IgnoreSignatures query bool false "whether to skip the verification of `Release` file signatures"
// @Success 200 {object} deb.RemoteRepo
// @Failure 400 {object} Error "Bad Request"
// @Router /api/mirrors [post]
func apiMirrorsCreate(c *gin.Context) {
var err error
var b struct {
@@ -129,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"
@@ -168,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()
@@ -188,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()
@@ -266,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

10
api/packages.go
View File

@@ -16,7 +16,15 @@ func apiPackagesShow(c *gin.Context) {
c.JSON(200, p)
}
// GET /api/packages
// @Summary Get packages
// @Description Get list of packages.
// @Tags Packages
// @Consume json
// @Produce json
// @Param q query string false "search query"
// @Param format query string false "format: `details` for more detailed information"
// @Success 200 {array} string "List of packages"
// @Router /api/packages [get]
func apiPackages(c *gin.Context) {
collectionFactory := context.NewCollectionFactory()
collection := collectionFactory.PackageCollection()

7
api/publish.go
View File

@@ -52,7 +52,12 @@ func parseEscapedPath(path string) string {
return result
}
// GET /publish
// @Summary Get publish points
// @Description Get list of available publish points. Each publish point is returned as in “show” API.
// @Tags Publish
// @Produce json
// @Success 200 {array} deb.PublishedRepo
// @Router /api/publish [get]
func apiPublishList(c *gin.Context) {
collectionFactory := context.NewCollectionFactory()
collection := collectionFactory.PublishedRepoCollection()

45
api/repos.go
View File

@@ -50,7 +50,12 @@ func reposServeInAPIMode(c *gin.Context) {
c.FileFromFS(pkgpath, http.Dir(publicPath))
}
// GET /api/repos
// @Summary Get repos
// @Description Get list of available repos. Each repo is returned as in “show” API.
// @Tags Repos
// @Produce json
// @Success 200 {array} deb.LocalRepo
// @Router /api/repos [get]
func apiReposList(c *gin.Context) {
result := []*deb.LocalRepo{}
@@ -64,7 +69,18 @@ func apiReposList(c *gin.Context) {
c.JSON(200, result)
}
// POST /api/repos
// @Summary Create repository
// @Description Create a local repository.
// @Tags Repos
// @Produce json
// @Consume json
// @Param Name query string false "Name of repository to be created."
// @Param Comment query string false "Text describing local repository, for the user"
// @Param DefaultDistribution query string false "Default distribution when publishing from this local repo"
// @Param DefaultComponent query string false "Default component when publishing from this local repo"
// @Success 201 {object} deb.LocalRepo
// @Failure 400 {object} Error "Repository already exists"
// @Router /api/repos [post]
func apiReposCreate(c *gin.Context) {
var b struct {
Name string `binding:"required"`
@@ -143,6 +159,14 @@ func apiReposEdit(c *gin.Context) {
}
// GET /api/repos/:name
// @Summary Get repository info by name
// @Description Returns basic information about local repository.
// @Tags Repos
// @Produce json
// @Param name path string true "Repository name"
// @Success 200 {object} deb.LocalRepo
// @Failure 404 {object} Error "Repository not found"
// @Router /api/repos/{name} [get]
func apiReposShow(c *gin.Context) {
collectionFactory := context.NewCollectionFactory()
collection := collectionFactory.LocalRepoCollection()
@@ -295,7 +319,22 @@ func apiReposPackageFromFile(c *gin.Context) {
apiReposPackageFromDir(c)
}
// POST /repos/:name/file/:dir
// @Summary Add packages from uploaded file/directory
// @Description Import packages from files (uploaded using File Upload API) to the local repository. If directory specified, aptly would discover package files automatically.
// @Description Adding same package to local repository is not an error.
// @Description By default aptly would try to remove every successfully processed file and directory `dir` (if it becomes empty after import).
// @Tags Repos
// @Param name path string true "Repository name"
// @Param dir path string true "Directory to add"
// @Consume json
// @Param noRemove query string false "when value is set to 1, don’t remove any files"
// @Param forceReplace query string false "when value is set to 1, remove packages conflicting with package being added (in local repository)"
// @Produce json
// @Success 200 {string} string "OK"
// @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]
func apiReposPackageFromDir(c *gin.Context) {
forceReplace := c.Request.URL.Query().Get("forceReplace") == "1"
noRemove := c.Request.URL.Query().Get("noRemove") == "1"

7
api/s3.go
View File

@@ -4,7 +4,12 @@ import (
"github.com/gin-gonic/gin"
)
// GET /api/s3
// @Summary Get S3 buckets
// @Description Get list of S3 buckets.
// @Tags S3
// @Produce json
// @Success 200 {array} string "List of S3 buckets"
// @Router /api/s3 [get]
func apiS3List(c *gin.Context) {
keys := []string{}
for k := range context.Config().S3PublishRoots {

7
api/snapshot.go
View File

@@ -12,7 +12,12 @@ import (
"github.com/gin-gonic/gin"
)
// GET /api/snapshots
// @Summary Get snapshots
// @Description Get list of available snapshots. Each snapshot is returned as in “show” API.
// @Tags Snapshots
// @Produce json
// @Success 200 {array} deb.Snapshot
// @Router /api/snapshots [get]
func apiSnapshotsList(c *gin.Context) {
SortMethodString := c.Request.URL.Query().Get("sort")

7
api/task.go
View File

@@ -9,7 +9,12 @@ import (
"github.com/gin-gonic/gin"
)
// GET /tasks
// @Summary Get tasks
// @Description Get list of available tasks. Each task is returned as in “show” API.
// @Tags Tasks
// @Produce json
// @Success 200 {array} task.Task
// @Router /api/tasks [get]
func apiTasksList(c *gin.Context) {
list := context.TaskList()
c.JSON(200, list.GetTasks())