Add swagger docs for bucket endpoints

pkg/models/kanban.go

@@ -65,6 +65,16 @@ func getBucketByID(id int64) (b *Bucket, err error) {
 }
 
 // ReadAll returns all buckets with their tasks for a certain list
+// @Summary Get all kanban buckets of a list
+// @Description Returns all kanban buckets with belong to a list including their tasks.
+// @tags task
+// @Accept json
+// @Produce json
+// @Security JWTKeyAuth
+// @Param id path int true "List Id"
+// @Success 200 {array} models.Bucket "The buckets with their tasks"
+// @Failure 500 {object} models.Message "Internal server error"
+// @Router /lists/{id}/buckets [get]
 func (b *Bucket) ReadAll(auth web.Auth, search string, page int, perPage int) (result interface{}, resultCount int, numberOfTotalItems int64, err error) {
 
 	// Note: I'm ignoring pagination for now since I've yet to figure out a way on how to make it work
@@ -129,6 +139,19 @@ func (b *Bucket) ReadAll(auth web.Auth, search string, page int, perPage int) (r
 }
 
 // Create creates a new bucket
+// @Summary Create a new bucket
+// @Description Creates a new kanban bucket on a list.
+// @tags task
+// @Accept json
+// @Produce json
+// @Security JWTKeyAuth
+// @Param id path int true "List Id"
+// @Param bucket body models.Bucket true "The bucket object"
+// @Success 200 {object} models.Bucket "The created bucket object."
+// @Failure 400 {object} code.vikunja.io/web.HTTPError "Invalid bucket object provided."
+// @Failure 404 {object} code.vikunja.io/web.HTTPError "The list does not exist."
+// @Failure 500 {object} models.Message "Internal error"
+// @Router /lists/{id}/buckets [put]
 func (b *Bucket) Create(a web.Auth) (err error) {
 	b.CreatedByID = a.GetID()
 
@@ -137,12 +160,38 @@ func (b *Bucket) Create(a web.Auth) (err error) {
 }
 
 // Update Updates an existing bucket
+// @Summary Update an existing bucket
+// @Description Updates an existing kanban bucket.
+// @tags task
+// @Accept json
+// @Produce json
+// @Security JWTKeyAuth
+// @Param listID path int true "List Id"
+// @Param bucketID path int true "Bucket Id"
+// @Param bucket body models.Bucket true "The bucket object"
+// @Success 200 {object} models.Bucket "The created bucket object."
+// @Failure 400 {object} code.vikunja.io/web.HTTPError "Invalid bucket object provided."
+// @Failure 404 {object} code.vikunja.io/web.HTTPError "The bucket does not exist."
+// @Failure 500 {object} models.Message "Internal error"
+// @Router /lists/{listID}/buckets/{bucketID} [post]
 func (b *Bucket) Update() (err error) {
 	_, err = x.Where("id = ?", b.ID).Update(b)
 	return
 }
 
 // Delete removes a bucket, but no tasks
+// @Summary Deletes an existing bucket
+// @Description Deletes an existing kanban bucket and dissociates all of its task. It does not delete any tasks.
+// @tags task
+// @Accept json
+// @Produce json
+// @Security JWTKeyAuth
+// @Param listID path int true "List Id"
+// @Param bucketID path int true "Bucket Id"
+// @Success 200 {object} models.Message "Successfully deleted."
+// @Failure 404 {object} code.vikunja.io/web.HTTPError "The bucket does not exist."
+// @Failure 500 {object} models.Message "Internal error"
+// @Router /lists/{listID}/buckets/{bucketID} [delete]
 func (b *Bucket) Delete() (err error) {
 	// Remove all associations of tasks to that bucket
 	_, err = x.Where("bucket_id = ?", b.ID).Cols("bucket_id").Update(&Task{BucketID: 0})

pkg/routes/routes.go

@@ -246,6 +246,16 @@ func registerAPIRoutes(a *echo.Group) {
 	}
 	a.GET("/lists/:list/tasks", taskCollectionHandler.ReadAllWeb)
 
+	kanbanBucketHandler := &handler.WebHandler{
+		EmptyStruct: func() handler.CObject {
+			return &models.Bucket{}
+		},
+	}
+	a.GET("/lists/:list/buckets", kanbanBucketHandler.ReadAllWeb)
+	a.PUT("/lists/:list/buckets", kanbanBucketHandler.CreateWeb)
+	a.POST("/lists/:list/buckets/:bucket", kanbanBucketHandler.UpdateWeb)
+	a.DELETE("/lists/:list/buckets/:bucket", kanbanBucketHandler.DeleteWeb)
+
 	taskHandler := &handler.WebHandler{
 		EmptyStruct: func() handler.CObject {
 			return &models.Task{}