Added docs via swagger

routes/api/v1/item_delete.go

@@ -1,13 +1,38 @@
 package v1
 
 import (
-	"github.com/labstack/echo"
-	"strconv"
-	"net/http"
 	"git.kolaente.de/konrad/list/models"
+	"github.com/labstack/echo"
+	"net/http"
+	"strconv"
 )
 
 func DeleteListItemByIDtemByID(c echo.Context) error {
+	// swagger:operation DELETE /item/{itemID} lists deleteListItem
+	// ---
+	// summary: Deletes a list item
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: itemID
+	//   in: path
+	//   description: ID of the list item to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Message"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "403":
+	//     "$ref": "#/responses/Message"
+	//   "404":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
 	// Check if we have our ID
 	id := c.Param("id")
 	// Make int
@@ -36,4 +61,4 @@ func DeleteListItemByIDtemByID(c echo.Context) error {
 	}
 
 	return c.JSON(http.StatusOK, models.Message{"The item was deleted with success."})
-}
+}

routes/api/v1/list_delete.go

@@ -1,13 +1,38 @@
 package v1
 
 import (
-	"github.com/labstack/echo"
-	"strconv"
-	"net/http"
 	"git.kolaente.de/konrad/list/models"
+	"github.com/labstack/echo"
+	"net/http"
+	"strconv"
 )
 
 func DeleteListByID(c echo.Context) error {
+	// swagger:operation DELETE /lists/{listID} lists deleteList
+	// ---
+	// summary: Deletes a list with all items on it
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: listID
+	//   in: path
+	//   description: ID of the list to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Message"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "403":
+	//     "$ref": "#/responses/Message"
+	//   "404":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
 	// Check if we have our ID
 	id := c.Param("id")
 	// Make int
@@ -36,4 +61,4 @@ func DeleteListByID(c echo.Context) error {
 	}
 
 	return c.JSON(http.StatusOK, models.Message{"The list was deleted with success."})
-}
+}

routes/api/v1/list_item_add_update.go

@@ -8,6 +8,33 @@ import (
 )
 
 func AddListItem(c echo.Context) error {
+	// swagger:operation PUT /lists/{listID} lists addListItem
+	// ---
+	// summary: Adds an item to a list
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: listID
+	//   in: path
+	//   description: ID of the list to use
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/ListItem"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ListItem"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
+	// TODO: return 403 if you dont have the right to add an item to that list
+
 	// Get the list ID
 	id := c.Param("id")
 	// Make int
@@ -20,6 +47,31 @@ func AddListItem(c echo.Context) error {
 }
 
 func UpdateListItem(c echo.Context) error {
+	// swagger:operation PUT /item/{itemID} lists updateListItem
+	// ---
+	// summary: Updates a list item
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: itemID
+	//   in: path
+	//   description: ID of the item to update
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/ListItem"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ListItem"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
 	// Get the item ID
 	id := c.Param("id")
 	// Make int
@@ -73,4 +125,4 @@ func updateOrCreateListItemHelper(listID, itemID int64, c echo.Context) error {
 	}
 
 	return c.JSON(http.StatusOK, finalItem)
-}
+}

routes/api/v1/list_show.go

@@ -9,6 +9,27 @@ import (
 
 // AddOrUpdateList Adds or updates a new list
 func GetListByID(c echo.Context) error {
+	// swagger:operation GET /lists/{listID} lists getList
+	// ---
+	// summary: gets one list with all todo items
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: listID
+	//   in: path
+	//   description: ID of the list to show
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/List"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
 	// Check if we have our ID
 	id := c.Param("id")
 	// Make int

routes/api/v1/lists_add_update.go

@@ -7,8 +7,65 @@ import (
 	"strconv"
 )
 
+func AddList(c echo.Context) error {
+	// swagger:operation PUT /lists lists addList
+	// ---
+	// summary: Creates a new list owned by the currently logged in user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/List"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/List"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "403":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
+	return addOrUpdateList(c)
+}
+
+func UpdateList(c echo.Context) error {
+	// swagger:operation POST /lists/{listID} lists upadteList
+	// ---
+	// summary: Updates a list
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: listID
+	//   in: path
+	//   description: ID of the list to update
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/List"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/List"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "403":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
+	return addOrUpdateList(c)
+}
+
 // AddOrUpdateList Adds or updates a new list
-func AddOrUpdateList(c echo.Context) error {
+func addOrUpdateList(c echo.Context) error {
 
 	// Get the list
 	var list *models.List

routes/api/v1/lists_list.go

@@ -8,6 +8,18 @@ import (
 
 // GetListsByUser gets all lists a user owns
 func GetListsByUser(c echo.Context) error {
+	// swagger:operation GET /lists lists getLists
+	// ---
+	// summary: Gets all lists owned by the current user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/List"
+	//   "500":
+	//     "$ref": "#/responses/Message"
 
 	currentUser, err := models.GetCurrentUser(c)
 	if err != nil {

routes/api/v1/login.go

@@ -12,6 +12,26 @@ import (
 
 // Login is the login handler
 func Login(c echo.Context) error {
+	// swagger:operation POST /login user login
+	// ---
+	// summary: Logs a user in. Returns a JWT-Token to authenticate requests
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/UserLogin"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/Token"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "403":
+	//     "$ref": "#/responses/Message"
+
 	u := new(models.UserLogin)
 	if err := c.Bind(u); err != nil {
 		return c.JSON(http.StatusBadRequest, models.Message{"Please provide a username and password."})

routes/api/v1/swagger/options.go

@@ -0,0 +1,22 @@
+package swagger
+
+import "git.kolaente.de/konrad/list/models"
+
+// not actually a response, just a hack to get go-swagger to include definitions
+// of the various XYZOption structs
+
+// parameterBodies
+// swagger:response parameterBodies
+type swaggerParameterBodies struct {
+	// in:body
+	UserLogin models.UserLogin
+
+	// in:body
+	ApiUserPassword models.ApiUserPassword
+
+	// in:body
+	List models.List
+
+	// in:body
+	ListItem models.ListItem
+}

routes/api/v1/swagger/responses.go

@@ -0,0 +1,52 @@
+package swagger
+
+import "git.kolaente.de/konrad/list/models"
+
+// Message
+// swagger:response Message
+type swaggerResponseMessage struct {
+	// in:body
+	Body models.Message `json:"body"`
+}
+
+// ================
+// User definitions
+// ================
+
+// User Object
+// swagger:response User
+type swaggerResponseUser struct {
+	// in:body
+	Body models.User `json:"body"`
+}
+
+// Token
+// swagger:response Token
+type swaggerResponseToken struct {
+	// The body message
+	// in:body
+	Body struct {
+		// The token
+		//
+		// Required: true
+		Token string `json:"token"`
+	} `json:"body"`
+}
+
+// ================
+// List definitions
+// ================
+
+// List
+// swagger:response List
+type swaggerResponseLIst struct {
+	// in:body
+	Body models.List `json:"body"`
+}
+
+// ListItem
+// swagger:response ListItem
+type swaggerResponseLIstItem struct {
+	// in:body
+	Body models.ListItem `json:"body"`
+}

routes/api/v1/user_add_update.go

@@ -1,36 +1,47 @@
 package v1
 
 import (
-	"encoding/json"
 	"git.kolaente.de/konrad/list/models"
 	"github.com/labstack/echo"
 	"net/http"
 	"strconv"
-	"strings"
 )
 
-// UserAddOrUpdate is the handler to add a user
-func UserAddOrUpdate(c echo.Context) error {
+func RegisterUser(c echo.Context) error {
+
+	// swagger:operation POST /register user register
+	// ---
+	// summary: Creates a new user account
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/ApiUserPassword"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/User"
+	//   "400":
+	//     "$ref": "#/responses/Message"
+	//   "500":
+	//     "$ref": "#/responses/Message"
+
+	return userAddOrUpdate(c)
+}
+
+// userAddOrUpdate is the handler to add a user
+func userAddOrUpdate(c echo.Context) error {
 
 	// TODO: prevent everyone from updating users
 
 	// Check for Request Content
-	userFromString := c.FormValue("user")
-	var datUser *models.User
+	var datUser *models.ApiUserPassword
 
-	if userFromString == "" {
-		// b := new(models.User)
-		if err := c.Bind(&datUser); err != nil {
-			return c.JSON(http.StatusBadRequest, models.Message{"No user model provided."})
-		}
-	} else {
-		// Decode the JSON
-		dec := json.NewDecoder(strings.NewReader(userFromString))
-		err := dec.Decode(&datUser)
-
-		if err != nil {
-			return c.JSON(http.StatusBadRequest, models.Message{"Error decoding user: " + err.Error()})
-		}
+	if err := c.Bind(&datUser); err != nil {
+		return c.JSON(http.StatusBadRequest, models.Message{"No user model provided."})
 	}
 
 	// Check if we have an ID other than the one in the struct
@@ -54,9 +65,9 @@ func UserAddOrUpdate(c echo.Context) error {
 	// Insert or update the user
 	var newUser models.User
 	if exists {
-		newUser, err = models.UpdateUser(*datUser)
+		newUser, err = models.UpdateUser(datUser.APIFormat())
 	} else {
-		newUser, err = models.CreateUser(*datUser)
+		newUser, err = models.CreateUser(datUser.APIFormat())
 	}
 
 	if err != nil {
@@ -88,8 +99,5 @@ func UserAddOrUpdate(c echo.Context) error {
 		return c.JSON(http.StatusInternalServerError, models.Message{"Error"})
 	}
 
-	// Obfuscate his password
-	newUser.Password = ""
-
 	return c.JSON(http.StatusOK, newUser)
 }