[#34] Update update api documentation & Increase api version

docs/package.go

@@ -16,7 +16,7 @@
 //
 //     Schemes: http, https
 //     Host: localhost
-//     Version: 1.0.3
+//     Version: 1.0.4
 //     License: MIT https://github.com/gotify/server/blob/master/LICENSE
 //
 //     Consumes:

docs/spec.json

@@ -17,7 +17,7 @@
       "name": "MIT",
       "url": "https://github.com/gotify/server/blob/master/LICENSE"
     },
-    "version": "1.0.3"
+    "version": "1.0.4"
   },
   "host": "localhost",
   "paths": {
@@ -267,6 +267,22 @@
             "name": "id",
             "in": "path",
             "required": true
+          },
+          {
+            "maximum": 200,
+            "minimum": 1,
+            "type": "integer",
+            "default": 100,
+            "description": "the maximal amount of messages to return",
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "minimum": 0,
+            "type": "integer",
+            "description": "return all messages with an ID less than this value",
+            "name": "since",
+            "in": "query"
           }
         ],
         "responses": {
@@ -275,7 +291,7 @@
             "schema": {
               "type": "array",
               "items": {
-                "$ref": "#/definitions/Message"
+                "$ref": "#/definitions/PagedMessages"
               }
             }
           },
@@ -615,13 +631,31 @@
         ],
         "summary": "Return all messages.",
         "operationId": "getMessages",
+        "parameters": [
+          {
+            "maximum": 200,
+            "minimum": 1,
+            "type": "integer",
+            "default": 100,
+            "description": "the maximal amount of messages to return",
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "minimum": 0,
+            "type": "integer",
+            "description": "return all messages with an ID less than this value",
+            "name": "since",
+            "in": "query"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Ok",
             "schema": {
               "type": "array",
               "items": {
-                "$ref": "#/definitions/Message"
+                "$ref": "#/definitions/PagedMessages"
               }
             }
           },
@@ -1280,6 +1314,77 @@
       },
       "x-go-package": "github.com/gotify/server/model"
     },
+    "PagedMessages": {
+      "description": "Wrapper for the paging and the messages",
+      "type": "object",
+      "title": "PagedMessages Model",
+      "required": [
+        "paging",
+        "messages"
+      ],
+      "properties": {
+        "messages": {
+          "description": "The messages.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Message"
+          },
+          "x-go-name": "Messages",
+          "readOnly": true
+        },
+        "paging": {
+          "$ref": "#/definitions/Paging"
+        }
+      },
+      "x-go-package": "github.com/gotify/server/model"
+    },
+    "Paging": {
+      "description": "The Paging holds holds information about the limit and making requests to the next page.",
+      "type": "object",
+      "title": "Paging Model",
+      "required": [
+        "size",
+        "since",
+        "limit"
+      ],
+      "properties": {
+        "limit": {
+          "description": "The limit of the messages for the current request.",
+          "type": "integer",
+          "format": "int64",
+          "maximum": 200,
+          "minimum": 1,
+          "x-go-name": "Limit",
+          "readOnly": true,
+          "example": 123
+        },
+        "next": {
+          "description": "The request url for the next page. Empty/Null when no next page is available.",
+          "type": "string",
+          "x-go-name": "Next",
+          "readOnly": true,
+          "example": "http://example.com/message?limit=50\u0026since=123456"
+        },
+        "since": {
+          "description": "The ID of the last message returned in the current request. Use this as alternative to the next link.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0,
+          "x-go-name": "Since",
+          "readOnly": true,
+          "example": 5
+        },
+        "size": {
+          "description": "The amount of messages that got returned in the current request.",
+          "type": "integer",
+          "format": "int64",
+          "x-go-name": "Size",
+          "readOnly": true,
+          "example": 5
+        }
+      },
+      "x-go-package": "github.com/gotify/server/model"
+    },
     "User": {
       "description": "The User holds information about permission and other stuff.",
       "type": "object",

router/router.go

@@ -260,13 +260,27 @@ func Create(db *database.GormDatabase, vInfo *model.VersionInfo, conf *config.Co
 				//   description: the application id
 				//   required: true
 				//   type: integer
+				// - name: limit
+				//   in: query
+				//   description: the maximal amount of messages to return
+				//   required: false
+				//   maximum: 200
+				//   minimum: 1
+				//   default: 100
+				//   type: integer
+				// - name: since
+				//   in: query
+				//   description: return all messages with an ID less than this value
+				//   minimum: 0
+				//   required: false
+				//   type: integer
 				// responses:
 				//   200:
 				//     description: Ok
 				//     schema:
 				//       type: array
 				//       items:
-				//         $ref: "#/definitions/Message"
+				//         $ref: "#/definitions/PagedMessages"
 				//   401:
 				//     description: Unauthorized
 				//     schema:
@@ -422,13 +436,28 @@ func Create(db *database.GormDatabase, vInfo *model.VersionInfo, conf *config.Co
 			// - clientTokenHeader: []
 			// - clientTokenQuery: []
 			// - basicAuth: []
+			// parameters:
+			// - name: limit
+			//   in: query
+			//   description: the maximal amount of messages to return
+			//   required: false
+			//   maximum: 200
+			//   minimum: 1
+			//   default: 100
+			//   type: integer
+			// - name: since
+			//   in: query
+			//   description: return all messages with an ID less than this value
+			//   minimum: 0
+			//   required: false
+			//   type: integer
 			// responses:
 			//   200:
 			//     description: Ok
 			//     schema:
 			//       type: array
 			//       items:
-			//         $ref: "#/definitions/Message"
+			//         $ref: "#/definitions/PagedMessages"
 			//   401:
 			//     description: Unauthorized
 			//     schema: