From d097aef12ce47d0cc2f67e6ba8daec8c79aef4ec Mon Sep 17 00:00:00 2001 From: Saad Ur Rahman Date: Tue, 5 Nov 2024 15:27:45 -0500 Subject: [PATCH 1/2] [Go] package upgrades. --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 3a58495..7a491be 100644 --- a/go.mod +++ b/go.mod @@ -7,7 +7,7 @@ require ( github.com/gin-gonic/gin v1.10.0 github.com/go-playground/validator/v10 v10.22.0 github.com/gocql/gocql v1.6.0 - github.com/golang-jwt/jwt/v4 v4.5.0 + github.com/golang-jwt/jwt/v4 v4.5.1 github.com/golang/mock v1.6.0 github.com/pkg/errors v0.9.1 github.com/redis/go-redis/v9 v9.6.1 diff --git a/go.sum b/go.sum index 6d3c187..ecce400 100644 --- a/go.sum +++ b/go.sum @@ -79,8 +79,8 @@ github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU= github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I= github.com/gocql/gocql v1.6.0 h1:IdFdOTbnpbd0pDhl4REKQDM+Q0SzKXQ1Yh+YZZ8T/qU= github.com/gocql/gocql v1.6.0/go.mod h1:3gM2c4D3AnkISwBxGnMMsS8Oy4y2lhbPRsH4xnJrHG8= -github.com/golang-jwt/jwt/v4 v4.5.0 h1:7cYmW1XlMY7h7ii7UhUyChSgS5wUJEnm9uZVTGqOWzg= -github.com/golang-jwt/jwt/v4 v4.5.0/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0= +github.com/golang-jwt/jwt/v4 v4.5.1 h1:JdqV9zKUdtaa9gdPlywC3aeoEsR681PlKC+4F5gQgeo= +github.com/golang-jwt/jwt/v4 v4.5.1/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0= github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc= github.com/golang/mock v1.6.0/go.mod h1:p6yTPP+5HYm5mzsMV8JkE6ZKdX+/wYM6Hr+LicevLPs= github.com/golang/snappy v0.0.3/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q= From 4299dbc93e8dcd3ee6e0bc33c32e8a1e86d37a22 Mon Sep 17 00:00:00 2001 From: Saad Ur Rahman Date: Tue, 5 Nov 2024 15:29:41 -0500 Subject: [PATCH 2/2] [REST] update of OpenAPI docs. --- docs/docs.go | 24 ++-- docs/swagger.json | 20 +--- docs/swagger.yaml | 15 +-- pkg/http/rest/handlers/healthcheck.go | 16 +-- pkg/http/rest/handlers/quiz.go | 154 +++++++++++++------------- pkg/http/rest/handlers/score.go | 86 +++++++------- pkg/http/rest/handlers/users.go | 98 ++++++++-------- pkg/http/rest/rest.go | 34 +++--- 8 files changed, 213 insertions(+), 234 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index dbeb5e2..326d366 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -1,5 +1,5 @@ -// Code generated by swaggo/swag. DO NOT EDIT. - +// Package docs GENERATED BY SWAG; DO NOT EDIT +// This file was generated by swaggo/swag package docs import "github.com/swaggo/swag" @@ -1016,17 +1016,6 @@ const docTemplate = `{ } } }, - "model_http.Metadata": { - "type": "object", - "properties": { - "num_records": { - "type": "integer" - }, - "quiz_id": { - "type": "string" - } - } - }, "model_http.StatsResponse": { "type": "object", "properties": { @@ -1038,8 +1027,11 @@ const docTemplate = `{ } } }, - "metadata": { - "$ref": "#/definitions/model_http.Metadata" + "num_records": { + "type": "integer" + }, + "quiz_id": { + "type": "string" }, "records": { "type": "array", @@ -1070,7 +1062,7 @@ const docTemplate = `{ // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ - Version: "1.7.5", + Version: "1.7.6", Host: "localhost:44243", BasePath: "/api/rest/v1", Schemes: []string{"http"}, diff --git a/docs/swagger.json b/docs/swagger.json index 2979ab5..2cc7c2d 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -21,7 +21,7 @@ "name": "GPL-3.0", "url": "https://opensource.org/licenses/GPL-3.0" }, - "version": "1.7.5" + "version": "1.7.6" }, "host": "localhost:44243", "basePath": "/api/rest/v1", @@ -1012,17 +1012,6 @@ } } }, - "model_http.Metadata": { - "type": "object", - "properties": { - "num_records": { - "type": "integer" - }, - "quiz_id": { - "type": "string" - } - } - }, "model_http.StatsResponse": { "type": "object", "properties": { @@ -1034,8 +1023,11 @@ } } }, - "metadata": { - "$ref": "#/definitions/model_http.Metadata" + "num_records": { + "type": "integer" + }, + "quiz_id": { + "type": "string" }, "records": { "type": "array", diff --git a/docs/swagger.yaml b/docs/swagger.yaml index e64c416..72489e6 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -171,13 +171,6 @@ definitions: - threshold - token type: object - model_http.Metadata: - properties: - num_records: - type: integer - quiz_id: - type: string - type: object model_http.StatsResponse: properties: links: @@ -185,8 +178,10 @@ definitions: next_page: type: string type: object - metadata: - $ref: '#/definitions/model_http.Metadata' + num_records: + type: integer + quiz_id: + type: string records: items: $ref: '#/definitions/model_cassandra.Response' @@ -211,7 +206,7 @@ info: name: GPL-3.0 url: https://opensource.org/licenses/GPL-3.0 title: Multiple Choice Question Platform. - version: 1.7.5 + version: 1.7.6 paths: /health: get: diff --git a/pkg/http/rest/handlers/healthcheck.go b/pkg/http/rest/handlers/healthcheck.go index bdfa269..a11b12d 100644 --- a/pkg/http/rest/handlers/healthcheck.go +++ b/pkg/http/rest/handlers/healthcheck.go @@ -12,14 +12,14 @@ import ( ) // Healthcheck checks if the service is healthy. -// @Summary Healthcheck for service liveness. -// @Description This endpoint is exposed to allow load balancers etc. to check the health of the service. -// @Tags health healthcheck liveness -// @Id healthcheck -// @Produce json -// @Success 200 {object} model_http.Success "message: healthy" -// @Failure 503 {object} model_http.Error "error message with any available details" -// @Router /health [get] +// @Summary Healthcheck for service liveness. +// @Description This endpoint is exposed to allow load balancers etc. to check the health of the service. +// @Tags health healthcheck liveness +// @Id healthcheck +// @Produce json +// @Success 200 {object} model_http.Success "message: healthy" +// @Failure 503 {object} model_http.Error "error message with any available details" +// @Router /health [get] func Healthcheck(logger *logger.Logger, db cassandra.Cassandra, cache redis.Redis) gin.HandlerFunc { return func(context *gin.Context) { var err error diff --git a/pkg/http/rest/handlers/quiz.go b/pkg/http/rest/handlers/quiz.go index c47abcb..94d8f29 100644 --- a/pkg/http/rest/handlers/quiz.go +++ b/pkg/http/rest/handlers/quiz.go @@ -18,18 +18,18 @@ import ( ) // ViewQuiz will retrieve a test using a variable in the URL. -// @Summary View a quiz. -// @Description This endpoint will retrieve a quiz with a provided quiz ID if it is published. -// @Tags view test quiz -// @Id viewQuiz -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The quiz ID for the quiz being requested." -// @Success 200 {object} model_http.Success "The message will contain the quiz ID and the payload will contain the quiz" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 404 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/view/{quiz_id} [get] +// @Summary View a quiz. +// @Description This endpoint will retrieve a quiz with a provided quiz ID if it is published. +// @Tags view test quiz +// @Id viewQuiz +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The quiz ID for the quiz being requested." +// @Success 200 {object} model_http.Success "The message will contain the quiz ID and the payload will contain the quiz" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 404 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/view/{quiz_id} [get] func ViewQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, cache redis.Redis) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -79,20 +79,20 @@ func ViewQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, cac } // CreateQuiz will submit a quiz and write back the GetScore ID. -// @Summary Create a quiz. -// @Description This endpoint will create a quiz with randomly generated Test ID and associate it with the requester. -// @Description The username will be extracted from the JWT and associated with the Test ID. -// @Tags create test quiz -// @Id createQuiz -// @Accept json -// @Produce json -// @Security ApiKeyAuth -// @Param quiz body model_cassandra.QuizCore true "The Quiz to be created as unpublished" -// @Success 200 {object} model_http.Success "The message will contain the Quiz ID of the newly generated quiz" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 409 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/create/ [post] +// @Summary Create a quiz. +// @Description This endpoint will create a quiz with randomly generated Test ID and associate it with the requester. +// @Description The username will be extracted from the JWT and associated with the Test ID. +// @Tags create test quiz +// @Id createQuiz +// @Accept json +// @Produce json +// @Security ApiKeyAuth +// @Param quiz body model_cassandra.QuizCore true "The Quiz to be created as unpublished" +// @Success 200 {object} model_http.Success "The message will contain the Quiz ID of the newly generated quiz" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 409 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/create/ [post] func CreateQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -136,20 +136,20 @@ func CreateQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) g } // UpdateQuiz will update a quiz. -// @Summary Update a quiz. -// @Description This endpoint will update a quiz with the provided Test ID if it was created by the requester and is not published. -// @Tags update modify test quiz -// @Id updateQuiz -// @Accept json -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the quiz being updated." -// @Param quiz body model_cassandra.QuizCore true "The Quiz to replace the one already submitted" -// @Success 200 {object} model_http.Success "The message will contain a confirmation of the update" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/update/{quiz_id} [patch] +// @Summary Update a quiz. +// @Description This endpoint will update a quiz with the provided Test ID if it was created by the requester and is not published. +// @Tags update modify test quiz +// @Id updateQuiz +// @Accept json +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the quiz being updated." +// @Param quiz body model_cassandra.QuizCore true "The Quiz to replace the one already submitted" +// @Success 200 {object} model_http.Success "The message will contain a confirmation of the update" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/update/{quiz_id} [patch] func UpdateQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -199,17 +199,17 @@ func UpdateQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) g } // DeleteQuiz will delete a quiz using a variable in the URL. -// @Summary Delete a quiz. -// @Description This endpoint will mark a quiz as delete if it was created by the requester. The provided Test ID is provided is a path parameter. -// @Tags delete remove test quiz -// @Id deleteQuiz -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the quiz being deleted." -// @Success 200 {object} model_http.Success "The message will contain a confirmation of deletion" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/delete/{quiz_id} [delete] +// @Summary Delete a quiz. +// @Description This endpoint will mark a quiz as delete if it was created by the requester. The provided Test ID is provided is a path parameter. +// @Tags delete remove test quiz +// @Id deleteQuiz +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the quiz being deleted." +// @Success 200 {object} model_http.Success "The message will contain a confirmation of deletion" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/delete/{quiz_id} [delete] func DeleteQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, cache redis.Redis) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -272,18 +272,18 @@ func DeleteQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, c } // PublishQuiz will publish a quiz using a variable in the URL. -// @Summary Publish a quiz. -// @Description When a quiz is submitted it is not published by default and is thus unavailable to be taken. -// @Description This endpoint will publish a quiz with the provided Test ID if it was created by the requester. -// @Tags publish test quiz create -// @Id publishQuiz -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the quiz being published." -// @Success 200 {object} model_http.Success "The message will contain a confirmation of publishing" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/publish/{quiz_id} [patch] +// @Summary Publish a quiz. +// @Description When a quiz is submitted it is not published by default and is thus unavailable to be taken. +// @Description This endpoint will publish a quiz with the provided Test ID if it was created by the requester. +// @Tags publish test quiz create +// @Id publishQuiz +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the quiz being published." +// @Success 200 {object} model_http.Success "The message will contain a confirmation of publishing" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/publish/{quiz_id} [patch] func PublishQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, cache redis.Redis) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -338,20 +338,20 @@ func PublishQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, } // TakeQuiz will submit the answers to a quiz using a variable in the URL. -// @Summary Take a quiz. -// @Description Take a quiz by submitting an answer sheet. The username will be extracted from the JWT and associated with the scorecard. -// @Tags take test quiz submit answer -// @Id takeQuiz -// @Accept json -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the answers being submitted." -// @Param answers body model_cassandra.QuizResponse true "The answer card to be submitted." -// @Success 200 {object} model_http.Success "Score will be in the payload" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /quiz/take/{quiz_id} [post] +// @Summary Take a quiz. +// @Description Take a quiz by submitting an answer sheet. The username will be extracted from the JWT and associated with the scorecard. +// @Tags take test quiz submit answer +// @Id takeQuiz +// @Accept json +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the answers being submitted." +// @Param answers body model_cassandra.QuizResponse true "The answer card to be submitted." +// @Success 200 {object} model_http.Success "Score will be in the payload" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /quiz/take/{quiz_id} [post] func TakeQuiz(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, cache redis.Redis, grader grading.Grading) gin.HandlerFunc { return func(context *gin.Context) { var err error diff --git a/pkg/http/rest/handlers/score.go b/pkg/http/rest/handlers/score.go index 7daf910..af6a786 100644 --- a/pkg/http/rest/handlers/score.go +++ b/pkg/http/rest/handlers/score.go @@ -17,18 +17,18 @@ import ( ) // GetScore will retrieve a test score with the provided test id and the username from the JWT payload. -// @Summary Get a user's score. -// @Description Gets a scorecard for a user. Extracts username from the JWT and Test ID is provided as a path parameter. -// @Tags score scores -// @Id getScore -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the requested scorecard." -// @Success 200 {object} model_http.Success "Score will be in the payload" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 404 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /score/test/{quiz_id} [get] +// @Summary Get a user's score. +// @Description Gets a scorecard for a user. Extracts username from the JWT and Test ID is provided as a path parameter. +// @Tags score scores +// @Id getScore +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the requested scorecard." +// @Success 200 {object} model_http.Success "Score will be in the payload" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 404 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /score/test/{quiz_id} [get] func GetScore(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -66,20 +66,20 @@ func GetScore(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin } // GetStats will retrieve test statistics with the provided test id and the username from the JWT payload. -// @Summary Get all statistics associated with a specific test. -// @Description Gets the statistics associated with a specific test if the user created the test. -// @Description Extracts username from the JWT and the Test ID is provided as a path parameter. -// @Tags score scores stats statistics -// @Id getStats -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the requested statistics." -// @Success 200 {object} model_http.Success "Statistics will be in the payload" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 404 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /score/stats/{quiz_id} [get] +// @Summary Get all statistics associated with a specific test. +// @Description Gets the statistics associated with a specific test if the user created the test. +// @Description Extracts username from the JWT and the Test ID is provided as a path parameter. +// @Tags score scores stats statistics +// @Id getStats +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the requested statistics." +// @Success 200 {object} model_http.Success "Statistics will be in the payload" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 404 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /score/stats/{quiz_id} [get] func GetStats(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -123,23 +123,23 @@ func GetStats(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin } // GetStatsPage will retrieve paginated test statistics with the provided test id and the username from the JWT payload. -// @Summary Get paginated statistics associated with a specific test. -// @Description Gets the paginated statistics associated with a specific test if the user created the test. -// @Description Extracts username from the JWT and the Test ID is provided as a query parameter. -// @Description A query string to be appended to the next request to retrieve the next page of data will be returned in the response. -// @Tags score scores stats statistics -// @Id getStatsPaged -// @Produce json -// @Security ApiKeyAuth -// @Param quiz_id path string true "The Test ID for the requested statistics." -// @Param pageCursor query string false "The page cursor into the query results records." -// @Param pageSize query int false "The number of records to retrieve on this page." -// @Success 200 {object} model_http.StatsResponse "A page of statistics data" -// @Failure 400 {object} model_http.Error "Error message with any available details in payload" -// @Failure 403 {object} model_http.Error "Error message with any available details in payload" -// @Failure 404 {object} model_http.Error "Error message with any available details in payload" -// @Failure 500 {object} model_http.Error "Error message with any available details in payload" -// @Router /score/stats-paged/{quiz_id} [get] +// @Summary Get paginated statistics associated with a specific test. +// @Description Gets the paginated statistics associated with a specific test if the user created the test. +// @Description Extracts username from the JWT and the Test ID is provided as a query parameter. +// @Description A query string to be appended to the next request to retrieve the next page of data will be returned in the response. +// @Tags score scores stats statistics +// @Id getStatsPaged +// @Produce json +// @Security ApiKeyAuth +// @Param quiz_id path string true "The Test ID for the requested statistics." +// @Param pageCursor query string false "The page cursor into the query results records." +// @Param pageSize query int false "The number of records to retrieve on this page." +// @Success 200 {object} model_http.StatsResponse "A page of statistics data" +// @Failure 400 {object} model_http.Error "Error message with any available details in payload" +// @Failure 403 {object} model_http.Error "Error message with any available details in payload" +// @Failure 404 {object} model_http.Error "Error message with any available details in payload" +// @Failure 500 {object} model_http.Error "Error message with any available details in payload" +// @Router /score/stats-paged/{quiz_id} [get] func GetStatsPage(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error diff --git a/pkg/http/rest/handlers/users.go b/pkg/http/rest/handlers/users.go index 66031ad..8f786a3 100644 --- a/pkg/http/rest/handlers/users.go +++ b/pkg/http/rest/handlers/users.go @@ -17,18 +17,18 @@ import ( ) // RegisterUser will handle an HTTP request to create a user. -// @Summary Register a user. -// @Description Creates a user account by inserting credentials into the database. A hashed password is stored. -// @Tags user users register security -// @Id registerUser -// @Accept json -// @Produce json -// @Param user body model_cassandra.UserAccount true "Username, password, first and last name, email address of user" -// @Success 200 {object} model_http.JWTAuthResponse "a valid JWT token for the new account" -// @Failure 400 {object} model_http.Error "error message with any available details in payload" -// @Failure 409 {object} model_http.Error "error message with any available details in payload" -// @Failure 500 {object} model_http.Error "error message with any available details in payload" -// @Router /user/register [post] +// @Summary Register a user. +// @Description Creates a user account by inserting credentials into the database. A hashed password is stored. +// @Tags user users register security +// @Id registerUser +// @Accept json +// @Produce json +// @Param user body model_cassandra.UserAccount true "Username, password, first and last name, email address of user" +// @Success 200 {object} model_http.JWTAuthResponse "a valid JWT token for the new account" +// @Failure 400 {object} model_http.Error "error message with any available details in payload" +// @Failure 409 {object} model_http.Error "error message with any available details in payload" +// @Failure 500 {object} model_http.Error "error message with any available details in payload" +// @Router /user/register [post] func RegisterUser(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -67,18 +67,18 @@ func RegisterUser(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) } // LoginUser validates login credentials and generates a JWT. -// @Summary Login a user. -// @Description Logs in a user by validating credentials and returning a JWT. -// @Tags user users login security -// @Id loginUser -// @Accept json -// @Produce json -// @Param credentials body model_cassandra.UserLoginCredentials true "Username and password to login with" -// @Success 200 {object} model_http.JWTAuthResponse "JWT in the api-key" -// @Failure 400 {object} model_http.Error "error message with any available details in payload" -// @Failure 403 {object} model_http.Error "error message with any available details in payload" -// @Failure 500 {object} model_http.Error "error message with any available details in payload" -// @Router /user/login [post] +// @Summary Login a user. +// @Description Logs in a user by validating credentials and returning a JWT. +// @Tags user users login security +// @Id loginUser +// @Accept json +// @Produce json +// @Param credentials body model_cassandra.UserLoginCredentials true "Username and password to login with" +// @Success 200 {object} model_http.JWTAuthResponse "JWT in the api-key" +// @Failure 400 {object} model_http.Error "error message with any available details in payload" +// @Failure 403 {object} model_http.Error "error message with any available details in payload" +// @Failure 500 {object} model_http.Error "error message with any available details in payload" +// @Router /user/login [post] func LoginUser(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -118,18 +118,18 @@ func LoginUser(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra) gi } // LoginRefresh validates a JWT token and issues a fresh token. -// @Summary Refresh a user's JWT by extending its expiration time. -// @Description Refreshes a user's JWT by validating it and then issuing a fresh JWT with an extended validity time. JWT must be expiring in under 60 seconds. -// @Tags user users login refresh security -// @Id loginRefresh -// @Produce json -// @Security ApiKeyAuth -// @Success 200 {object} model_http.JWTAuthResponse "A new valid JWT" -// @Failure 400 {object} model_http.Error "error message with any available details in payload" -// @Failure 403 {object} model_http.Error "error message with any available details in payload" -// @Failure 500 {object} model_http.Error "error message with any available details in payload" -// @Failure 510 {object} model_http.Error "error message with any available details in payload" -// @Router /user/refresh [post] +// @Summary Refresh a user's JWT by extending its expiration time. +// @Description Refreshes a user's JWT by validating it and then issuing a fresh JWT with an extended validity time. JWT must be expiring in under 60 seconds. +// @Tags user users login refresh security +// @Id loginRefresh +// @Produce json +// @Security ApiKeyAuth +// @Success 200 {object} model_http.JWTAuthResponse "A new valid JWT" +// @Failure 400 {object} model_http.Error "error message with any available details in payload" +// @Failure 403 {object} model_http.Error "error message with any available details in payload" +// @Failure 500 {object} model_http.Error "error message with any available details in payload" +// @Failure 510 {object} model_http.Error "error message with any available details in payload" +// @Router /user/refresh [post] func LoginRefresh(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, authHeaderKey string) gin.HandlerFunc { return func(context *gin.Context) { var err error @@ -173,19 +173,19 @@ func LoginRefresh(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, } // DeleteUser will mark a user as deleted in the database. -// @Summary Deletes a user. The user must supply their credentials as well as a confirmation message. -// @Description Deletes a user stored in the database by marking it as deleted. The user must supply their login credentials as well as complete the following confirmation message: "I understand the consequences, delete my user account USERNAME HERE" -// @Tags user users delete security -// @Id deleteUser -// @Accept json -// @Produce json -// @Security ApiKeyAuth -// @Param request body model_http.DeleteUserRequest true "The request payload for deleting an account" -// @Success 200 {object} model_http.Success "message with a confirmation of a deleted user account" -// @Failure 400 {object} model_http.Error "error message with any available details in payload" -// @Failure 409 {object} model_http.Error "error message with any available details in payload" -// @Failure 500 {object} model_http.Error "error message with any available details in payload" -// @Router /user/delete [delete] +// @Summary Deletes a user. The user must supply their credentials as well as a confirmation message. +// @Description Deletes a user stored in the database by marking it as deleted. The user must supply their login credentials as well as complete the following confirmation message: "I understand the consequences, delete my user account USERNAME HERE" +// @Tags user users delete security +// @Id deleteUser +// @Accept json +// @Produce json +// @Security ApiKeyAuth +// @Param request body model_http.DeleteUserRequest true "The request payload for deleting an account" +// @Success 200 {object} model_http.Success "message with a confirmation of a deleted user account" +// @Failure 400 {object} model_http.Error "error message with any available details in payload" +// @Failure 409 {object} model_http.Error "error message with any available details in payload" +// @Failure 500 {object} model_http.Error "error message with any available details in payload" +// @Router /user/delete [delete] func DeleteUser(logger *logger.Logger, auth auth.Auth, db cassandra.Cassandra, authHeaderKey string) gin.HandlerFunc { return func(context *gin.Context) { var err error diff --git a/pkg/http/rest/rest.go b/pkg/http/rest/rest.go index 8796d35..ef34077 100644 --- a/pkg/http/rest/rest.go +++ b/pkg/http/rest/rest.go @@ -104,28 +104,28 @@ func (s *Server) Run() { func (s *Server) initialize() { s.router = gin.Default() - // @title Multiple Choice Question Platform. - // @version 1.7.5 - // @description Multiple Choice Question Platform API. - // @description This application supports the creation, managing, marking, viewing, retrieving stats, and scores of quizzes. + // @title Multiple Choice Question Platform. + // @version 1.7.6 + // @description Multiple Choice Question Platform API. + // @description This application supports the creation, managing, marking, viewing, retrieving stats, and scores of quizzes. // - // @schemes http - // @host localhost:44243 - // @BasePath /api/rest/v1 + // @schemes http + // @host localhost:44243 + // @BasePath /api/rest/v1 // - // @accept json - // @produce json + // @accept json + // @produce json // - // @contact.name Saad Ur Rahman - // @contact.url https://www.linkedin.com/in/saad-ur-rahman/ - // @contact.email saad.ur.rahman@gmail.com + // @contact.name Saad Ur Rahman + // @contact.url https://www.linkedin.com/in/saad-ur-rahman/ + // @contact.email saad.ur.rahman@gmail.com // - // @license.name GPL-3.0 - // @license.url https://opensource.org/licenses/GPL-3.0 + // @license.name GPL-3.0 + // @license.url https://opensource.org/licenses/GPL-3.0 // - // @securityDefinitions.apikey ApiKeyAuth - // @in header - // @name Authorization + // @securityDefinitions.apikey ApiKeyAuth + // @in header + // @name Authorization s.router.GET(s.conf.Server.SwaggerPath, ginSwagger.WrapHandler(swaggerfiles.Handler))