swagger.json

{
    "swagger": "2.0",
    "info": {
        "description": "This is Znotify api server.",
        "title": "ZNotify API",
        "contact": {
            "name": "Issues",
            "url": "https://github.com/ZNotify/server/issues"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.0"
    },
    "paths": {
        "/": {
            "get": {
                "description": "Provide UI",
                "produces": [
                    "text/html"
                ],
                "tags": [
                    "UI"
                ],
                "summary": "Web Index",
                "operationId": "webIndex",
                "responses": {
                    "200": {
                        "description": "html",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/alive": {
            "get": {
                "description": "If the server is alive",
                "produces": [
                    "text/plain"
                ],
                "tags": [
                    "Health"
                ],
                "summary": "Server Heartbeat",
                "operationId": "alive",
                "responses": {
                    "204": {
                        "description": "No Content",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/check": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Check if the user secret is valid",
                "operationId": "checkUserSecret",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "query",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-bool"
                        }
                    }
                }
            }
        },
        "/docs": {
            "get": {
                "produces": [
                    "text/plain"
                ],
                "tags": [
                    "UI"
                ],
                "summary": "Redirect to docs",
                "operationId": "docRedirect",
                "responses": {
                    "301": {
                        "description": "Moved Permanently",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/login": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "Login with GitHub",
                "operationId": "userLogin",
                "responses": {
                    "307": {
                        "description": "Temporary Redirect"
                    }
                }
            }
        },
        "/login/github": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "OAuth callback for GitHub, redirect to ui with user_secret",
                "operationId": "githubOAuthCallback",
                "parameters": [
                    {
                        "type": "string",
                        "description": "should always be 'no_need_to_set_state'",
                        "name": "state",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "access code",
                        "name": "code",
                        "in": "query",
                        "required": true
                    }
                ],
                "responses": {
                    "307": {
                        "description": "Temporary Redirect"
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        },
        "/webpush": {
            "get": {
                "description": "Check if this znotify instance support webpush and get public key",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Push"
                ],
                "summary": "Endpoint for webpush info check",
                "operationId": "webpush",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-push_info"
                        }
                    }
                }
            }
        },
        "/{user_secret}": {
            "post": {
                "description": "Send notification to user_id",
                "consumes": [
                    "text/plain"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Message"
                ],
                "summary": "Send notification",
                "operationId": "sendMessageLite",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Message Content",
                        "name": "string",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-models_Message"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        },
        "/{user_secret}/conn": {
            "get": {
                "description": "Work as a fallback strategy for device without public push provider, each frame in this connection will be a push message",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Push"
                ],
                "summary": "Endpoint for websocket connection",
                "operationId": "websocket",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Device ID, usually a UUID",
                        "name": "X-Device-ID",
                        "in": "header",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.Message"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        },
        "/{user_secret}/device/{device_id}": {
            "put": {
                "description": "Create or update device information",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Device"
                ],
                "summary": "Create or update device",
                "operationId": "createDevice",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "device_id should be a valid UUID",
                        "name": "device_id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "enum": [
                            "FCM",
                            "WebPush",
                            "WNS",
                            "Telegram",
                            "WebSocket"
                        ],
                        "type": "string",
                        "description": "channel can be used.",
                        "name": "channel",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "device name",
                        "name": "device_name",
                        "in": "formData"
                    },
                    {
                        "type": "string",
                        "description": "additional device meta",
                        "name": "device_meta",
                        "in": "formData"
                    },
                    {
                        "type": "string",
                        "description": "channel token",
                        "name": "token",
                        "in": "formData"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-bool"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            },
            "delete": {
                "description": "Delete device with device_id",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Device"
                ],
                "summary": "Delete device",
                "operationId": "deleteDevice",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "The identifier of device, should be a UUID",
                        "name": "device_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-bool"
                        }
                    }
                }
            }
        },
        "/{user_secret}/devices": {
            "get": {
                "description": "Delete device with device_id",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get user devices",
                "operationId": "getDevicesByUserSecret",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-array_models_Device"
                        }
                    }
                }
            }
        },
        "/{user_secret}/message/{id}": {
            "get": {
                "description": "Get message record detail of a message",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Message"
                ],
                "summary": "Get message record detail",
                "operationId": "getMessageById",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "ID of message",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-models_Message"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/common.NotFoundResponse"
                        }
                    }
                }
            },
            "delete": {
                "description": "Delete message record with id",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Message"
                ],
                "summary": "Delete message record",
                "operationId": "deleteMessageById",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "ID of message",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-bool"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        },
        "/{user_secret}/messages": {
            "get": {
                "description": "Get messages of user with pagination",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get messages of user",
                "operationId": "getMessagesByUserSecret",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "minimum": 0,
                        "type": "integer",
                        "default": 0,
                        "description": "The number of records to skip",
                        "name": "skip",
                        "in": "query"
                    },
                    {
                        "maximum": 100,
                        "minimum": 0,
                        "type": "integer",
                        "default": 20,
                        "description": "The number of records to return",
                        "name": "limit",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-array_models_Message"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        },
        "/{user_secret}/send": {
            "post": {
                "description": "Send notification to user_id",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Message"
                ],
                "summary": "Send notification",
                "operationId": "sendMessage",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Secret of user",
                        "name": "user_secret",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "default": "Notification",
                        "description": "Message Title",
                        "name": "title",
                        "in": "formData"
                    },
                    {
                        "type": "string",
                        "description": "Message Content",
                        "name": "content",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Long Message Content (optional)",
                        "name": "long",
                        "in": "formData"
                    },
                    {
                        "enum": [
                            "low",
                            "normal",
                            "high"
                        ],
                        "type": "string",
                        "default": "normal",
                        "description": "The priority of message",
                        "name": "priority",
                        "in": "formData"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/common.Response-models_Message"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/common.BadRequestResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/common.UnauthorizedResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "common.BadRequestResponse": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "string"
                },
                "code": {
                    "type": "integer",
                    "default": 400
                }
            }
        },
        "common.NotFoundResponse": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "string"
                },
                "code": {
                    "type": "integer",
                    "default": 404
                }
            }
        },
        "common.Response-array_models_Device": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/models.Device"
                    }
                },
                "code": {
                    "type": "integer",
                    "default": 200
                }
            }
        },
        "common.Response-array_models_Message": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/models.Message"
                    }
                },
                "code": {
                    "type": "integer",
                    "default": 200
                }
            }
        },
        "common.Response-bool": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "boolean"
                },
                "code": {
                    "type": "integer",
                    "default": 200
                }
            }
        },
        "common.Response-models_Message": {
            "type": "object",
            "properties": {
                "body": {
                    "$ref": "#/definitions/models.Message"
                },
                "code": {
                    "type": "integer",
                    "default": 200
                }
            }
        },
        "common.Response-push_info": {
            "type": "object",
            "properties": {
                "body": {
                    "$ref": "#/definitions/push.info"
                },
                "code": {
                    "type": "integer",
                    "default": 200
                }
            }
        },
        "common.UnauthorizedResponse": {
            "type": "object",
            "properties": {
                "body": {
                    "type": "string"
                },
                "code": {
                    "type": "integer",
                    "default": 401
                }
            }
        },
        "enum.Priority": {
            "type": "string",
            "enum": [
                "low",
                "normal",
                "high"
            ],
            "x-enum-comments": {
                "PriorityHigh": "high",
                "PriorityLow": "low",
                "PriorityNormal": "normal"
            },
            "x-enum-varnames": [
                "PriorityLow",
                "PriorityNormal",
                "PriorityHigh"
            ]
        },
        "enum.Sender": {
            "type": "string",
            "enum": [
                "FCM",
                "WebPush",
                "WNS",
                "Telegram",
                "WebSocket"
            ],
            "x-enum-comments": {
                "SenderFcm": "FCM",
                "SenderTelegram": "Telegram",
                "SenderWebPush": "WebPush",
                "SenderWebSocket": "WebSocket",
                "SenderWns": "WNS"
            },
            "x-enum-varnames": [
                "SenderFcm",
                "SenderWebPush",
                "SenderWns",
                "SenderTelegram",
                "SenderWebSocket"
            ]
        },
        "models.Device": {
            "type": "object",
            "properties": {
                "channel": {
                    "$ref": "#/definitions/enum.Sender"
                },
                "deviceMeta": {
                    "type": "string"
                },
                "deviceName": {
                    "type": "string"
                },
                "identifier": {
                    "type": "string"
                }
            }
        },
        "models.Message": {
            "type": "object",
            "properties": {
                "content": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "long": {
                    "type": "string"
                },
                "priority": {
                    "$ref": "#/definitions/enum.Priority"
                },
                "title": {
                    "type": "string"
                }
            }
        },
        "push.info": {
            "type": "object",
            "properties": {
                "enable": {
                    "type": "boolean"
                },
                "public_key": {
                    "type": "string"
                }
            }
        }
    },
    "tags": [
        {
            "description": "Device management",
            "name": "Device"
        },
        {
            "description": "User management",
            "name": "User"
        },
        {
            "description": "Message management",
            "name": "Message"
        },
        {
            "description": "Health check",
            "name": "Health"
        },
        {
            "description": "UI for documentation and WebPush",
            "name": "UI"
        },
        {
            "description": "Endpoint for push service",
            "name": "Push"
        }
    ]
}