colin
/
sharded-gotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add swagger documentation

This commit is contained in:
Jannis Mattheis 2018-02-16 21:43:31 +01:00 committed by Jannis Mattheis
parent 6a5357f9b3
commit e13aff389b
5 changed files with 1847 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/docs-packr.go Normal file
View File

File diff suppressed because one or more lines are too long

38
docs/package.go Normal file
View File

@ -0,0 +1,38 @@
// Package docs Gotify REST-API.
//
// This is the documentation of the Gotify REST-API.
//
// Schemes: http, https
// Host: localhost
// Version: 1.0.0
// License: MIT https://github.com/gotify/server/blob/master/LICENSE
// Contact: https://github.com/gotify/server/issues
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// SecurityDefinitions:
// appTokenQuery:
// type: apiKey
// name: token
// in: query
// clientTokenQuery:
// type: apiKey
// name: token
// in: query
// appTokenHeader:
// type: apiKey
// name: X-Gotify-Key
// in: header
// clientTokenHeader:
// type: apiKey
// name: X-Gotify-Key
// in: header
// basicAuth:
// type: basic
//
// swagger:meta
package docs

1172
docs/spec.json Normal file
View File

File diff suppressed because it is too large Load Diff

17
docs/swagger.go Normal file
View File

@ -0,0 +1,17 @@
package docs
import (
"github.com/gin-gonic/gin"
"github.com/gobuffalo/packr"
"strings"
)
// Serve serves the documentation.
func Serve(ctx *gin.Context) {
ctx.Writer.WriteString(get(ctx.Request.URL.Host))
}
func get(host string) string {
box := packr.NewBox("./")
return strings.Replace(box.String("spec.json"), "localhost", host, 1)
}

606
router/router.go
View File

@ -8,6 +8,11 @@ import (
"github.com/gotify/server/auth" "github.com/gotify/server/auth"
"github.com/gotify/server/database" "github.com/gotify/server/database"
"github.com/gotify/server/error" "github.com/gotify/server/error"
"github.com/jmattheis/go-packr-swagger-ui"
"net/http"
"github.com/gotify/server/docs"
"github.com/gotify/server/stream" "github.com/gotify/server/stream"
) )
@ -20,15 +25,47 @@ func Create(db *database.GormDatabase) (*gin.Engine, func()) {
userHandler := api.UserAPI{DB: db} userHandler := api.UserAPI{DB: db}
g := gin.New() g := gin.New()
g.Use(gin.Logger(), gin.Recovery(), error.Handler()) g.Use(gin.Logger(), gin.Recovery(), error.Handler())
g.NoRoute(error.NotFound()) g.NoRoute(error.NotFound())
g.GET("/") g.GET("/")
g.GET("/swagger", docs.Serve)
g.GET("/docs/*any", gin.WrapH(http.StripPrefix("/docs/", http.FileServer(swaggerui.GetBox()))))
g.Use(func(ctx *gin.Context) { g.Use(func(ctx *gin.Context) {
ctx.Header("Content-Type", "application/json") ctx.Header("Content-Type", "application/json")
}) })
// swagger:operation POST /message message createMessage
//
// Create a message.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - appTokenHeader: []
// - appTokenQuery: []
// parameters:
// - name: body
// in: body
// description: the message to add
// required: true
// schema:
// $ref: "#/definitions/Message"
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/Message"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
g.Group("/").Use(authentication.RequireApplicationToken()).POST("/message", messageHandler.CreateMessage) g.Group("/").Use(authentication.RequireApplicationToken()).POST("/message", messageHandler.CreateMessage)
clientAuth := g.Group("") clientAuth := g.Group("")
@ -36,33 +73,440 @@ func Create(db *database.GormDatabase) (*gin.Engine, func()) {
clientAuth.Use(authentication.RequireClient()) clientAuth.Use(authentication.RequireClient())
app := clientAuth.Group("/application") app := clientAuth.Group("/application")
{ {
// swagger:operation GET /application token getApps
//
// Return all applications.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/Application"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
app.GET("", tokenHandler.GetApplications) app.GET("", tokenHandler.GetApplications)
// swagger:operation POST /application token createApp
//
// Create an application.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: body
// in: body
// description: the application to add
// required: true
// schema:
// $ref: "#/definitions/Application"
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/Application"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
app.POST("", tokenHandler.CreateApplication) app.POST("", tokenHandler.CreateApplication)
// swagger:operation DELETE /application/{id} token deleteApp
//
// Delete an application.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: the application id
// required: true
// type: string
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
app.DELETE("/:id", tokenHandler.DeleteApplication) app.DELETE("/:id", tokenHandler.DeleteApplication)
tokenMessage := app.Group("/:id/message") tokenMessage := app.Group("/:id/message")
{ {
// swagger:operation GET /application/{id}/message message getAppMessages
//
// Return all messages from a specific application.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the application id
// required: true
// type: string
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/Message"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
tokenMessage.GET("", messageHandler.GetMessagesWithApplication) tokenMessage.GET("", messageHandler.GetMessagesWithApplication)
// swagger:operation DELETE /application/{id}/message message deleteAppMessages
//
// Delete all messages from a specific application.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the application id
// required: true
// type: string
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
tokenMessage.DELETE("", messageHandler.DeleteMessageWithApplication) tokenMessage.DELETE("", messageHandler.DeleteMessageWithApplication)
} }
} }
client := clientAuth.Group("/client") client := clientAuth.Group("/client")
{ {
// swagger:operation GET /client token getClients
//
// Return all clients.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/Client"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
client.GET("", tokenHandler.GetClients) client.GET("", tokenHandler.GetClients)
// swagger:operation POST /client token createClient
//
// Create a client.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: body
// in: body
// description: the client to add
// required: true
// schema:
// $ref: "#/definitions/Client"
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/Client"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
client.POST("", tokenHandler.CreateClient) client.POST("", tokenHandler.CreateClient)
// swagger:operation DELETE /client/{id} token deleteClient
//
// Delete a client.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// parameters:
// - name: id
// in: path
// description: the client id
// required: true
// type: string
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
client.DELETE("/:id", tokenHandler.DeleteClient) client.DELETE("/:id", tokenHandler.DeleteClient)
} }
message := clientAuth.Group("/message") message := clientAuth.Group("/message")
{ {
// swagger:operation GET /message message getMessages
//
// Return all messages.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/Message"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
message.GET("", messageHandler.GetMessages) message.GET("", messageHandler.GetMessages)
// swagger:operation DELETE /message message deleteMessages
//
// Delete all messages.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
message.DELETE("", messageHandler.DeleteMessages) message.DELETE("", messageHandler.DeleteMessages)
// swagger:operation DELETE /message/{id} message deleteMessage
//
// Deletes a message with an id.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the message id
// required: true
// type: integer
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
message.DELETE("/:id", messageHandler.DeleteMessage) message.DELETE("/:id", messageHandler.DeleteMessage)
} }
// swagger:operation GET /stream message streamMessages
//
// Websocket, return newly created messages.
//
// ---
// schema: ws, wss
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/Message"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
clientAuth.GET("/stream", streamHandler.Handle) clientAuth.GET("/stream", streamHandler.Handle)
// swagger:operation GET /current/user user currentUser
//
// Return the current user.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/User"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
clientAuth.GET("current/user", userHandler.GetCurrentUser) clientAuth.GET("current/user", userHandler.GetCurrentUser)
// swagger:operation POST /current/user/password user updateCurrentUser
//
// Update the password of the current user.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: body
// in: body
// description: the user
// required: true
// schema:
// $ref: "#/definitions/User"
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
clientAuth.POST("current/user/password", userHandler.ChangePassword) clientAuth.POST("current/user/password", userHandler.ChangePassword)
} }
@ -70,11 +514,171 @@ func Create(db *database.GormDatabase) (*gin.Engine, func()) {
{ {
authAdmin.Use(authentication.RequireAdmin()) authAdmin.Use(authentication.RequireAdmin())
// swagger:operation GET /user user getUsers
//
// Return all users.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// responses:
// 200:
// description: Ok
// schema:
// type: array
// items:
// $ref: "#/definitions/User"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
authAdmin.GET("", userHandler.GetUsers) authAdmin.GET("", userHandler.GetUsers)
// swagger:operation POST /user user createUser
//
// Create a user.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: body
// in: body
// description: the user to add
// required: true
// schema:
// $ref: "#/definitions/User"
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/User"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
authAdmin.POST("", userHandler.CreateUser) authAdmin.POST("", userHandler.CreateUser)
// swagger:operation DELETE /user/{id} user deleteUser
//
// Deletes a user.
//
// ---
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the user id
// required: true
// type: integer
// responses:
// 200:
// description: Ok
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
authAdmin.DELETE("/:id", userHandler.DeleteUserByID) authAdmin.DELETE("/:id", userHandler.DeleteUserByID)
// swagger:operation GET /user/{id} user getUser
//
// Get a user.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the user id
// required: true
// type: integer
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/User"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
authAdmin.GET("/:id", userHandler.GetUserByID) authAdmin.GET("/:id", userHandler.GetUserByID)
// swagger:operation POST /user/{id} user updateUser
//
// Update a user.
//
// ---
// consumes:
// - application/json
// produces:
// - application/json
// security:
// - clientTokenHeader: []
// - clientTokenQuery: []
// - basicAuth: []
// parameters:
// - name: id
// in: path
// description: the user id
// required: true
// type: integer
// - name: body
// in: body
// description: the updated user
// required: true
// schema:
// $ref: "#/definitions/User"
// responses:
// 200:
// description: Ok
// schema:
// $ref: "#/definitions/User"
// 401:
// description: Unauthorized
// schema:
// $ref: "#/definitions/Error"
// 403:
// description: Forbidden
// schema:
// $ref: "#/definitions/Error"
authAdmin.POST("/:id", userHandler.UpdateUserByID) authAdmin.POST("/:id", userHandler.UpdateUserByID)
} }
return g, streamHandler.Close return g, streamHandler.Close