From caef4ff74ff4993ebd9406cde5fba71c3498f7c6 Mon Sep 17 00:00:00 2001 From: Jannis Mattheis Date: Sun, 8 Apr 2018 15:02:50 +0200 Subject: [PATCH] [#34] Update update api documentation & Increase api version --- docs/package.go | 2 +- docs/spec.json | 111 +++++++++++++++++++++++++++++++++++++++++++++-- router/router.go | 33 +++++++++++++- 3 files changed, 140 insertions(+), 6 deletions(-) diff --git a/docs/package.go b/docs/package.go index 78cf04f..bfe0665 100644 --- a/docs/package.go +++ b/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: diff --git a/docs/spec.json b/docs/spec.json index 1c99991..b4a8bc5 100644 --- a/docs/spec.json +++ b/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", diff --git a/router/router.go b/router/router.go index e6d678e..3b49c92 100644 --- a/router/router.go +++ b/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: