add swagger documentation

api/repos.go

@@ -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"