diff --git a/.gitignore b/.gitignore index f5f8b98..63ad616 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,7 @@ config.yml # vendor/ *.code-workspace + +# Build documentation + +docs/ \ No newline at end of file diff --git a/internal/api/application.go b/internal/api/application.go index d14ae38..5ee6707 100644 --- a/internal/api/application.go +++ b/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 "" -// @Failure 500,404,403 {string} string "" +// @Success 200 "" +// @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 "" -// @Failure 500,404,403,404 {string} string "" +// @Success 200 "" +// @Failure 500,404,403 "" +// @Security BasicAuth // @Router /application/{id} [put] func (h *ApplicationHandler) UpdateApplication(ctx *gin.Context) { application, err := getApplication(ctx, h.DB) diff --git a/internal/api/health.go b/internal/api/health.go index 7c43159..9c3ff65 100644 --- a/internal/api/health.go +++ b/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) diff --git a/internal/api/notification.go b/internal/api/notification.go index 064c716..bca42de 100644 --- a/internal/api/notification.go +++ b/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, ¬ification) } -// 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) diff --git a/internal/api/user.go b/internal/api/user.go index 65e5159..b61af59 100644 --- a/internal/api/user.go +++ b/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 { diff --git a/internal/model/notification.go b/internal/model/notification.go index fc46221..6239236 100644 --- a/internal/model/notification.go +++ b/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{}