add openapi docu

.gitignore

@@ -20,3 +20,7 @@ config.yml
 # vendor/
 
 *.code-workspace
+
+# Build documentation
+
+docs/

internal/api/application.go

@@ -112,12 +112,12 @@ func (h *ApplicationHandler) updateApplication(ctx *gin.Context, a *model.Applic
 // CreateApplication godoc
 // @Summary Create Application
 // @Description Create a new application
-// @Accept mpfd
+// @Accept json,mpfd
 // @Produce json
 // @Param name query string true "Name of the application"
 // @Param strict_compatability query boolean false "Use strict compatability mode"
 // @Success 200 {object} model.Application
-// @Failure 400 {string} string ""
+// @Failure 400 ""
 // @Security BasicAuth
 // @Router /application [post]
 func (h *ApplicationHandler) CreateApplication(ctx *gin.Context) {
@@ -144,10 +144,11 @@ func (h *ApplicationHandler) CreateApplication(ctx *gin.Context) {
 // GetApplications godoc
 // @Summary Get Applications
 // @Description Get all applications from current user
-// @Accept mpfd
+// @Accept json,mpfd
 // @Produce json
 // @Success 200 {array} model.Application
-// @Failure 500 {string} string ""
+// @Failure 500 ""
+// @Security BasicAuth
 // @Router /application [get]
 func (h *ApplicationHandler) GetApplications(ctx *gin.Context) {
 	user := authentication.GetUser(ctx)
@@ -166,11 +167,12 @@ func (h *ApplicationHandler) GetApplications(ctx *gin.Context) {
 // GetApplication godoc
 // @Summary Get Application
 // @Description Get single application by ID
-// @Accept mpfd
+// @Accept json,mpfd
 // @Produce json
 // @Param id path int true "ID of the application"
 // @Success 200 {object} model.Application
-// @Failure 404,403 {string} string ""
+// @Failure 404,403 ""
+// @Security BasicAuth
 // @Router /application/{id} [get]
 func (h *ApplicationHandler) GetApplication(ctx *gin.Context) {
 	application, err := getApplication(ctx, h.DB)
@@ -195,11 +197,12 @@ func (h *ApplicationHandler) GetApplication(ctx *gin.Context) {
 // DeleteApplication godoc
 // @Summary Delete Application
 // @Description Delete an application
-// @Accept mpfd
+// @Accept json,mpfd
 // @Produce json
 // @Param id path int true "ID of the application"
-// @Success 200 {string} string ""
+// @Success 200 ""
-// @Failure 500,404,403 {string} string ""
+// @Failure 500,404,403 ""
+// @Security BasicAuth
 // @Router /application/{id} [delete]
 func (h *ApplicationHandler) DeleteApplication(ctx *gin.Context) {
 	application, err := getApplication(ctx, h.DB)
@@ -221,14 +224,15 @@ func (h *ApplicationHandler) DeleteApplication(ctx *gin.Context) {
 // UpdateApplication godoc
 // @Summary Update Application
 // @Description Update an application
-// @Accept mpfd
+// @Accept json,mpfd
 // @Produce json
 // @Param id path int true "ID of the application"
 // @Param name query string false "New name for the application"
 // @Param refresh_token query bool false "Generate new refresh token for the application"
 // @Param strict_compatability query bool false "Whether to use strict compataibility mode"
-// @Success 200 {string} string ""
+// @Success 200 ""
-// @Failure 500,404,403,404 {string} string ""
+// @Failure 500,404,403 ""
+// @Security BasicAuth
 // @Router /application/{id} [put]
 func (h *ApplicationHandler) UpdateApplication(ctx *gin.Context) {
 	application, err := getApplication(ctx, h.DB)

internal/api/health.go

@@ -11,7 +11,13 @@ type HealthHandler struct {
 	DB Database
 }
 
-// Health returns the health status of the server.
+// Health godoc
+// @Summary Health of the application
+// @Accept json,mpfd
+// @Produce json
+// @Success 200 ""
+// @Failure 500 ""
+// @Router /health [get]
 func (h *HealthHandler) Health(ctx *gin.Context) {
 	if err := h.DB.Health(); err != nil {
 		ctx.AbortWithError(http.StatusInternalServerError, err)

internal/api/notification.go

@@ -29,7 +29,19 @@ type NotificationHandler struct {
 	DP NotificationDispatcher
 }
 
-// CreateNotification is used to create a new notification for a user.
+// CreateNotification godoc
+// @Summary Create a Notification
+// @Description Creates a new notification for the given channel
+// @Accept json,mpfd
+// @Produce json
+// @Param message query string true "The message to send"
+// @Param title query string false "The title to send"
+// @Param priority query integer false "The notifications priority"
+// @Param extras query model.NotificationExtras false "JSON object with additional information"
+// @Param token query string true "Channels token, can also be provieded in the header"
+// @Success 200 {object} model.Notification
+// @Failure 500,404,403 ""
+// @Router /message [post]
 func (h *NotificationHandler) CreateNotification(ctx *gin.Context) {
 	var notification model.Notification
 
@@ -58,7 +70,16 @@ func (h *NotificationHandler) CreateNotification(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, &notification)
 }
 
-// DeleteNotification is used to delete (or mark as deleted) a notification for a user
+// DeleteNotification godoc
+// @Summary Delete a Notification
+// @Description Informs the channel that the notification is deleted
+// @Accept json,mpfd
+// @Produce json
+// @Param message_id path string true "ID of the message to delete"
+// @Param token query string true "Channels token, can also be provieded in the header"
+// @Success 200 ""
+// @Failure 500,404,403 ""
+// @Router /message/{message_id} [DELETE]
 func (h *NotificationHandler) DeleteNotification(ctx *gin.Context) {
 	application := authentication.GetApplication(ctx)
 	id, err := getMessageID(ctx)

internal/api/user.go

@@ -112,8 +112,20 @@ func (h *UserHandler) updateUser(ctx *gin.Context, u *model.User, updateUser mod
 	return nil
 }
 
-// CreateUser creates a new user.
+// CreateUser godoc
 // This method assumes that the requesting user has privileges.
+// @Summary Create a User
+// @Description Creates a new user
+// @Accept json,mpfd
+// @Produce json
+// @Param name query string true "Name of the user"
+// @Param is_admin query bool false "Whether to set the user as admin or not"
+// @Param matrix_id query string true "Matrix ID of the user in the format @user:domain.tld"
+// @Param password query string true "The users password"
+// @Success 200 {object} model.ExternalUser
+// @Failure 500,404,403 ""
+// @Security BasicAuth
+// @Router /user [post]
 func (h *UserHandler) CreateUser(ctx *gin.Context) {
 	var createUser model.CreateUser
 
@@ -137,8 +149,16 @@ func (h *UserHandler) CreateUser(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, user.IntoExternalUser())
 }
 
-// GetUsers returns all users.
+// GetUsers godoc
 // This method assumes that the requesting user has privileges.
+// @Summary Get Users
+// @Description Gets a list of all users
+// @Accept json,mpfd
+// @Produce json
+// @Success 200 {object} []model.ExternalUser
+// @Failure 500 ""
+// @Security BasicAuth
+// @Router /user [get]
 func (h *UserHandler) GetUsers(ctx *gin.Context) {
 	users, err := h.DB.GetUsers()
 	if success := successOrAbort(ctx, http.StatusInternalServerError, err); !success {
@@ -154,8 +174,17 @@ func (h *UserHandler) GetUsers(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, &externalUsers)
 }
 
-// GetUser returns the user with the specified ID.
+// GetUser godoc
 // This method assumes that the requesting user has privileges.
+// @Summary Get User
+// @Description Gets single user
+// @Accept json,mpfd
+// @Produce json
+// @Param id path integer true "The users id"
+// @Success 200 {object} model.ExternalUser
+// @Failure 500,404 ""
+// @Security BasicAuth
+// @Router /user/{id} [get]
 func (h *UserHandler) GetUser(ctx *gin.Context) {
 	user, err := getUser(ctx, h.DB)
 	if err != nil {
@@ -165,9 +194,17 @@ func (h *UserHandler) GetUser(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, user.IntoExternalUser())
 }
 
-// DeleteUser deletes a user with a certain ID.
+// DeleteUser godoc
-//
 // This method assumes that the requesting user has privileges.
+// @Summary Delete User
+// @Description Delete user
+// @Accept json,mpfd
+// @Produce json
+// @Param id path integer true "The users id"
+// @Success 200 ""
+// @Failure 500,404 ""
+// @Security BasicAuth
+// @Router /user/{id} [delete]
 func (h *UserHandler) DeleteUser(ctx *gin.Context) {
 	user, err := getUser(ctx, h.DB)
 	if err != nil {
@@ -194,10 +231,22 @@ func (h *UserHandler) DeleteUser(ctx *gin.Context) {
 	ctx.JSON(http.StatusOK, gin.H{})
 }
 
-// UpdateUser updates a user with a certain ID.
+// UpdateUser godoc
-//
 // This method assumes that the requesting user has privileges. If users can later update their own user, make sure they
 // cannot give themselves privileges.
+// @Summary Update User
+// @Description Update user information
+// @Accept json,mpfd
+// @Produce json
+// @Param id path integer true "The users id"
+// @Param name query string true "Name of the user"
+// @Param is_admin query bool false "Whether to set the user as admin or not"
+// @Param matrix_id query string true "Matrix ID of the user in the format @user:domain.tld"
+// @Param password query string true "The users password"
+// @Success 200 ""
+// @Failure 500,404,400 ""
+// @Security BasicAuth
+// @Router /user/{id} [put]
 func (h *UserHandler) UpdateUser(ctx *gin.Context) {
 	user, err := getUser(ctx, h.DB)
 	if err != nil {

internal/model/notification.go

@@ -21,3 +21,6 @@ type DeleteNotification struct {
 	ID   string    `json:"id" form:"id"`
 	Date time.Time `json:"date"`
 }
+
+// NotificationExtras is need to document Notification.Extras in a format that the tool can read.
+type NotificationExtras map[string]interface{}