From 3a2da091864023cb7648d8099e368ff7b717e1e9 Mon Sep 17 00:00:00 2001 From: Jannis Mattheis Date: Tue, 27 Feb 2018 19:52:35 +0100 Subject: [PATCH] Improve documentation --- docs/package.go | 13 ++++++++++++- model/application.go | 13 +++++++++++++ model/client.go | 9 +++++++++ model/error.go | 12 ++++++++++++ model/message.go | 26 ++++++++++++++++++++++++++ model/user.go | 16 ++++++++++++++++ model/version.go | 12 ++++++++++++ router/router.go | 2 ++ 8 files changed, 102 insertions(+), 1 deletion(-) diff --git a/docs/package.go b/docs/package.go index 4a1c601..477eab5 100644 --- a/docs/package.go +++ b/docs/package.go @@ -2,11 +2,22 @@ // // This is the documentation of the Gotify REST-API. // +// # Authentication +// In Gotify there are two token types: +// __clientToken__: a client is something that receives message and manages stuff like creating new tokens or delete messages. (f.ex this token should be used for an android app) +// __appToken__: an application is something that sends messages (f.ex. this token should be used for a shell script) +// +// The token can be either transmitted through a header named `X-Gotify-Key` or a query parameter named `token`. +// There is also the possibility to authenticate through basic auth, this should only be used for creating a clientToken. +// +// \--- +// +// Found a bug or have some questions? [Create an issue on GitHub](https://github.com/gotify/server/issues) +// // Schemes: http, https // Host: localhost // Version: 1.0.1 // License: MIT https://github.com/gotify/server/blob/master/LICENSE -// Contact: https://github.com/gotify/server/issues // // Consumes: // - application/json diff --git a/model/application.go b/model/application.go index 0708098..da72f7e 100644 --- a/model/application.go +++ b/model/application.go @@ -6,9 +6,22 @@ package model // // swagger:model Application type Application struct { + // The application id. Can be used as `appToken`. See Authentication. + // + // read only: true + // required: true + // example: AWH0wZ5r0Mbac.r ID string `gorm:"primary_key;unique_index" json:"id"` UserID uint `gorm:"index" json:"-"` + // The application name. This is how the application should be displayed to the user. + // + // required: true + // example: Backup Server Name string `form:"name" query:"name" json:"name" binding:"required"` + // The description of the application. + // + // required: true + // example: Backup server for the interwebs Description string `form:"description" query:"description" json:"description"` Messages []Message `json:"-"` } diff --git a/model/client.go b/model/client.go index f61bcbe..f6723cf 100644 --- a/model/client.go +++ b/model/client.go @@ -6,7 +6,16 @@ package model // // swagger:model Client type Client struct { + // The client id. Can be used as `clientToken`. See Authentication. + // + // read only: true + // required: true + // example: CWH0wZ5r0Mbac.r ID string `gorm:"primary_key;unique_index" json:"id"` UserID uint `gorm:"index" json:"-"` + // The client name. This is how the client should be displayed to the user. + // + // required: true + // example: Android Phone Name string `form:"name" query:"name" json:"name" binding:"required"` } diff --git a/model/error.go b/model/error.go index 2060c8e..e8bc4aa 100644 --- a/model/error.go +++ b/model/error.go @@ -6,7 +6,19 @@ package model // // swagger:model Error type Error struct { + // The general error message + // + // required: true + // example: Unauthorized Error string `json:"error"` + // The http error code. + // + // required: true + // example: 401 ErrorCode int `json:"errorCode"` + // The http error code. + // + // required: true + // example: you need to provide a valid access token or user credentials to access this api ErrorDescription string `json:"errorDescription"` } diff --git a/model/message.go b/model/message.go index a3e53a5..7c7bd84 100644 --- a/model/message.go +++ b/model/message.go @@ -8,10 +8,36 @@ import "time" // // swagger:model Message type Message struct { + // The message id. + // + // read only: true + // required: true + // example: 25 ID uint `gorm:"AUTO_INCREMENT;primary_key;index" json:"id"` + // The application id that send this message. + // + // read only: true + // required: true + // example: AWH0wZ5r0Mbac.r ApplicationID string `json:"appid"` + // The actual message. + // + // required: true + // example: Backup was successfully finished. Message string `form:"message" query:"message" json:"message" binding:"required"` + // The title of the message. + // + // required: true + // example: Backup Title string `form:"title" query:"title" json:"title" binding:"required"` + // The priority of the message. + // + // example: 2 Priority int `form:"priority" query:"priority" json:"priority"` + // The date the message was created. + // + // read only: true + // required: true + // example: 2018-02-27T19:36:10.5045044+01:00 Date time.Time `json:"date"` } diff --git a/model/user.go b/model/user.go index e3b756c..9cbc844 100644 --- a/model/user.go +++ b/model/user.go @@ -16,8 +16,24 @@ type User struct { // // swagger:model User type UserExternal struct { + // The user id. + // + // read only: true + // required: true + // example: 25 ID uint `json:"id"` + // The user name. For login. + // + // required: true + // example: unicorn Name string `binding:"required" json:"name" query:"name" form:"name"` + // The user password. For login. (Will not be returned by any API) + // + // required: true + // example: mypassword; !will not be returned by any API! Pass string `json:"pass,omitempty" form:"pass" query:"pass"` + // If the user is an administrator. + // + // example: true Admin bool `json:"admin" form:"admin" query:"admin"` } diff --git a/model/version.go b/model/version.go index 7591dbb..5f78832 100644 --- a/model/version.go +++ b/model/version.go @@ -4,8 +4,20 @@ package model // // swagger:model VersionInfo type VersionInfo struct { + // The current version. + // + // required: true + // example: 5.2.6 Version string `json:"version"` + // The git commit hash on which this binary was built. + // + // required: true + // example: ae9512b6b6feea56a110d59a3353ea3b9c293864 Commit string `json:"commit"` + // The date on which this binary was built. + // + // required: true + // example: 2018-02-27T19:36:10.5045044+01:00 BuildDate string `json:"buildDate"` } diff --git a/router/router.go b/router/router.go index 4bc395e..f495424 100644 --- a/router/router.go +++ b/router/router.go @@ -58,6 +58,8 @@ func Create(db *database.GormDatabase, vInfo *model.VersionInfo, conf *config.Co // // Create a message. // + // __NOTE__: This API ONLY accepts an application token as authentication. + // // --- // consumes: // - application/json