Skip to content

Commit

Permalink
Update repos, task, snapshot api docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@iofq
iofq committed Nov 19, 2024
1 parent ffafa55 commit c7b7567
Show file tree
Hide file tree
Showing 4 changed files with 270 additions and 176 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ azurite-stop:

swagger: swagger-install
# Generate swagger docs
@PATH=$(BINPATH)/:$(PATH) swag init --markdownFiles docs --generalInfo docs/swagger.conf
@PATH=$(BINPATH)/:$(PATH) swag init --parseDependency --parseInternal --markdownFiles docs --generalInfo docs/swagger.conf

etcd-install:
# Install etcd
Expand Down
179 changes: 117 additions & 62 deletions api/repos.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,12 @@ import (
"github.com/gin-gonic/gin"
)

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Serve HTML listing of repo
// @Description If ServeInAPIMode is enabled in aptly config,
// @Description this endpoint is enabled which returns an HTML listing of each repo that can be browsed
// @Tags Repos
// @Produce json
// @Success 200 {object} string "msg"
// @Failure 404 {object} Error "Not Found"
// @Produce html
// @Success 200 {object} string "HTML"
// @Router /api/repos [get]
func reposListInAPIMode(localRepos map[string]utils.FileSystemPublishRoot) gin.HandlerFunc {
return func(c *gin.Context) {
Expand All @@ -42,15 +41,14 @@ func reposListInAPIMode(localRepos map[string]utils.FileSystemPublishRoot) gin.H
}
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Serve package in API mode
// @Description If ServeInAPIMode is enabled in aptly config,
// @Description this api serves a specified package from storage
// @Tags Repos
// @Param storage path string true "Storage"
// @Param pkgPath path string true "Package Path" allowReserved=true
// @Produce json
// @Success 200 {object} string "msg"
// @Failure 404 {object} Error "Not Found"
// @Success 200 ""
// @Router /api/{storage}/{pkgPath} [get]
func reposServeInAPIMode(c *gin.Context) {
pkgpath := c.Param("pkgPath")
Expand Down Expand Up @@ -100,7 +98,8 @@ type repoCreateParams struct {
}

// @Summary Create repository
// @Description Create a local repository.
// @Description Create a local repository with specified parameters.
// @Description Distribution and component are used as defaults when publishing repo either directly or via snapshot.
// @Tags Repos
// @Produce json
// @Consume json
Expand Down Expand Up @@ -159,22 +158,24 @@ func apiReposCreate(c *gin.Context) {
c.JSON(http.StatusCreated, repo)
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
type reposEditParams struct {
Name *string
Comment *string
DefaultDistribution *string
DefaultComponent *string
}

// @Summary Update repo
// @Description **Update local repository meta information**
// @Tags Repos
// @Produce json
// @Success 200 {object} string "msg"
// @Param request body reposEditParams true "Parameters"
// @Success 200 {object} deb.LocalRepo "msg"
// @Failure 404 {object} Error "Not Found"
// @Failure 500 {object} Error "Internal Server Error"
// @Router /api/repos/{name} [put]
func apiReposEdit(c *gin.Context) {
var b struct {
Name *string
Comment *string
DefaultDistribution *string
DefaultComponent *string
}

var b reposEditParams

Check warning on line 178 in api/repos.go

View check run for this annotation

Codecov / codecov/patch

api/repos.go#L177-L178 

Added lines #L177 - L178 were not covered by tests
if c.Bind(&b) != nil {
return
}
Expand Down Expand Up @@ -238,13 +239,17 @@ func apiReposShow(c *gin.Context) {
c.JSON(200, repo)
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Drop Repository
// @Description Drop/delete a repo
// @Description Cannot drop repos that are published.
// @Description Needs force=1 to drop repos used as source by other repos.
// @Tags Repos
// @Produce json
// @Success 200 {object} string "msg"
// @Param _async query bool false "Run task in background using tasks API"
// @Param force query int false "force: 1 to enable"
// @Success 200 {object} task.ProcessReturnValue "Repo object"
// @Failure 404 {object} Error "Not Found"
// @Failure 404 {object} Error "Repo Conflict"
// @Router /api/repos/{name} [delete]
func apiReposDrop(c *gin.Context) {
force := c.Request.URL.Query().Get("force") == "1"
Expand Down Expand Up @@ -280,13 +285,19 @@ func apiReposDrop(c *gin.Context) {
})
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary List Repo Packages
// @Description **Return a list of packages present in the repo**
// @Description If `q` query parameter is missing, return all packages, otherwise return packages that match q
// @Tags Repos
// @Produce json
// @Param name path string true "Snapshot to search"
// @Param q query string true "Package query (e.g Name%20(~%20matlab))"
// @Param withDeps query string true "Set to 1 to include dependencies when evaluating package query"
// @Param format query string true "Set to 'details' to return extra info about each package"
// @Param maximumVersion query string true "Set to 1 to only return the highest version for each package name"
// @Success 200 {object} string "msg"
// @Failure 404 {object} Error "Not Found"
// @Failure 404 {object} Error "Internal Server Error"
// @Router /api/repos/{name}/packages [get]
func apiReposPackagesShow(c *gin.Context) {
collectionFactory := context.NewCollectionFactory()
Expand All @@ -307,11 +318,13 @@ func apiReposPackagesShow(c *gin.Context) {
showPackages(c, repo.RefList(), collectionFactory)
}

type reposPackagesAddDeleteParams struct {
PackageRefs []string
}

// Handler for both add and delete
func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error) {
var b struct {
PackageRefs []string
}
var b reposPackagesAddDeleteParams

if c.Bind(&b) != nil {
return
Expand Down Expand Up @@ -368,13 +381,20 @@ func apiReposPackagesAddDelete(c *gin.Context, taskNamePrefix string, cb func(li
})
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Add Packages by Key
// @Description **Add packages to local repository by package keys.**
// @Description
// @Description Any package can be added that is present in the aptly database (from any mirror, snapshot, local repository). This API combined with package list (search) APIs allows one to implement importing, copying, moving packages around.
// @Description
// @Description API verifies that packages actually exist in aptly database and checks constraint that conflicting packages can’t be part of the same local repository.
// @Tags Repos
// @Produce json
// @Param request body reposPackagesAddDeleteParams true "Parameters"
// @Param _async query bool false "Run task in background using tasks API"
// @Success 200 {object} string "msg"
// @Failure 400 {object} Error "Bad Request"
// @Failure 404 {object} Error "Not Found"
// @Failure 400 {object} Error "Internal Server Error"
// @Router /api/repos/{name}/packages [post]
func apiReposPackagesAdd(c *gin.Context) {
apiReposPackagesAddDelete(c, "Add packages to repo ", func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error {
Expand All @@ -383,13 +403,18 @@ func apiReposPackagesAdd(c *gin.Context) {
})
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Delete Packages by Key
// @Description **Remove packages from local repository by package keys.**
// @Description
// @Description Any package(s) can be removed from a local repository. Package references from a local repository can be retrieved with GET /api/repos/:name/packages.
// @Tags Repos
// @Produce json
// @Param request body reposPackagesAddDeleteParams true "Parameters"
// @Param _async query bool false "Run task in background using tasks API"
// @Success 200 {object} string "msg"
// @Failure 400 {object} Error "Bad Request"
// @Failure 404 {object} Error "Not Found"
// @Failure 400 {object} Error "Internal Server Error"
// @Router /api/repos/{name}/packages [delete]
func apiReposPackagesDelete(c *gin.Context) {
apiReposPackagesAddDelete(c, "Delete packages from repo ", func(list *deb.PackageList, p *deb.Package, out aptly.Progress) error {
Expand All @@ -399,23 +424,27 @@ func apiReposPackagesDelete(c *gin.Context) {
})
}

// @Summary Add packages
// @Description **Add package file**
// @Description To Do
// @Summary Add packages from uploaded file
// @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 of packages"
// @Param file path string false "Filename (optional)"
// @Param _async query bool false "Run task in background using tasks API"
// @Produce json
// @Success 200 {object} string "msg"
// @Failure 404 {object} Error "Not Found"
// @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}/file/{dir}/{file} [post]
func apiReposPackageFromFile(c *gin.Context) {
// redirect all work to dir method
apiReposPackageFromDir(c)
}

// @Summary Add packages from uploaded file/directory
// @Summary Add packages from uploaded 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).
Expand All @@ -425,6 +454,7 @@ func apiReposPackageFromFile(c *gin.Context) {
// @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)"
// @Param _async query bool false "Run task in background using tasks API"
// @Produce json
// @Success 200 {string} string "OK"
// @Failure 400 {object} Error "wrong file"
Expand Down Expand Up @@ -549,23 +579,31 @@ func apiReposPackageFromDir(c *gin.Context) {
})
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
type reposCopyPackageParams struct {
WithDeps bool `json:"with-deps,omitempty"`
DryRun bool `json:"dry-run,omitempty"`
}

// @Summary Copy Package
// @Description Copies a package from a source to destination repository
// @Tags Repos
// @Produce json
// @Success 200 {object} string "msg"
// @Param name path string true "Source repo"
// @Param src path string true "Destination repo"
// @Param file path string true "File/packages to copy"
// @Param _async query bool false "Run task in background using tasks API"
// @Success 200 {object} task.ProcessReturnValue "msg"
// @Failure 400 {object} Error "Bad Request"
// @Failure 404 {object} Error "Not Found"
// @Failure 422 {object} Error "Unprocessable Entity"
// @Failure 500 {object} Error "Internal Server Error"
// @Router /api/repos/{name}/copy/{src}/{file} [post]
func apiReposCopyPackage(c *gin.Context) {
dstRepoName := c.Params.ByName("name")
srcRepoName := c.Params.ByName("src")
fileName := c.Params.ByName("file")

jsonBody := struct {
WithDeps bool `json:"with-deps,omitempty"`
DryRun bool `json:"dry-run,omitempty"`
}{
jsonBody := reposCopyPackageParams{
WithDeps: false,
DryRun: false,
}
Expand Down Expand Up @@ -619,7 +657,6 @@ func apiReposCopyPackage(c *gin.Context) {
dstList, err := deb.NewPackageListFromRefList(dstRepo.RefList(), collectionFactory.PackageCollection(), context.Progress())
if err != nil {
return &task.ProcessReturnValue{Code: http.StatusInternalServerError, Value: nil}, fmt.Errorf("unable to load packages in dest: %s", err)

}

srcList, err := deb.NewPackageListFromRefList(srcRefList, collectionFactory.PackageCollection(), context.Progress())
Expand Down Expand Up @@ -695,11 +732,15 @@ func apiReposCopyPackage(c *gin.Context) {
})
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
// @Summary Include Packages from File Upload
// @Description Allows automatic processing of .changes file controlling package upload (uploaded using File Upload API) to the local repository. i.e. Exposes repo include command in api.
// @Tags Repos
// @Produce json
// @Param forceReplace query int false "when value is set to 1, when adding package that conflicts with existing package, remove existing package"
// @Param noRemoveFiles query int false "when value is set to 1, don’t remove files that have been imported successfully into repository"
// @Param acceptUnsigned query int false "when value is set to 1, accept unsigned .changes files"
// @Param ignoreSignature query int false "when value is set to 1 disable verification of .changes file signature"
// @Param _async query bool false "Run task in background using tasks API"
// @Success 200 {object} string "msg"
// @Failure 404 {object} Error "Not Found"
// @Router /api/repos/{name}/include/{dir}/{file} [post]
Expand All @@ -708,12 +749,27 @@ func apiReposIncludePackageFromFile(c *gin.Context) {
apiReposIncludePackageFromDir(c)
}

// @Summary TODO
// @Description **ToDo**
// @Description To Do
type reposIncludePackageFromDirReport struct {
Warnings []string
Added []string
Deleted []string
}

type reposIncludePackageFromDirResponse struct {
Report reposIncludePackageFromDirReport
FailedFiles []string
}

// @Summary Include Packages from Dir Upload
// @Description Allows automatic processing of .changes file controlling package upload (uploaded using File Upload API) to the local repository. i.e. Exposes repo include command in api.
// @Tags Repos
// @Produce json
// @Success 200 {object} string "msg"
// @Param forceReplace query int false "when value is set to 1, when adding package that conflicts with existing package, remove existing package"
// @Param noRemoveFiles query int false "when value is set to 1, don’t remove files that have been imported successfully into repository"
// @Param acceptUnsigned query int false "when value is set to 1, accept unsigned .changes files"
// @Param ignoreSignature query int false "when value is set to 1 disable verification of .changes file signature"
// @Param _async query bool false "Run task in background using tasks API"
// @Success 200 {object} reposIncludePackageFromDirResponse "Response"
// @Failure 404 {object} Error "Not Found"
// @Router /api/repos/{name}/include/{dir} [post]
func apiReposIncludePackageFromDir(c *gin.Context) {
Expand Down Expand Up @@ -817,6 +873,5 @@ func apiReposIncludePackageFromDir(c *gin.Context) {
"Report": reporter,
"FailedFiles": failedFiles,
}}, nil

})
}
Loading

0 comments on commit c7b7567

Please sign in to comment.