Improve documentation

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

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:"-"`
 }

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"`
 }

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"`
 }

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"`
 }

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"`
 }

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"`
 }
 

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