diff --git a/backend/docs/docs.go b/backend/docs/docs.go index 8b528ffe2..bc968e007 100644 --- a/backend/docs/docs.go +++ b/backend/docs/docs.go @@ -9,7 +9,10 @@ const docTemplate = `{ "info": { "description": "{{escape .Description}}", "title": "{{.Title}}", - "contact": {}, + "contact": { + "name": "Euan Meston", + "email": "euan@openweightlifting.org" + }, "version": "{{.Version}}" }, "host": "{{.Host}}", @@ -17,7 +20,7 @@ const docTemplate = `{ "paths": { "/event": { "post": { - "description": "Requires a case-sensitive event name to be passed to it.", + "description": "Requires a case-sensitive event name to be passed to it. This is still a work in progress.", "consumes": [ "application/json" ], @@ -51,13 +54,16 @@ const docTemplate = `{ } } } + }, + "204": { + "description": "No Content" } } } }, "/history": { "post": { - "description": "do ping", + "description": "Pull a lifter's history by name. The name must be an exact match and can be checked using the search endpoint.", "consumes": [ "application/json" ], @@ -67,13 +73,27 @@ const docTemplate = `{ "tags": [ "POST Requests" ], - "summary": "how to use the lifter history endpoint", + "summary": "Retrieve a lifter's history", + "parameters": [ + { + "description": "name", + "name": "name", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/structs.LifterHistory" } + }, + "204": { + "description": "No Content" } } } @@ -94,49 +114,49 @@ const docTemplate = `{ "parameters": [ { "type": "integer", - "description": "start", + "description": "Position to begin from within the full query", "name": "start", "in": "query" }, { "type": "integer", - "description": "stop", + "description": "Position to stop at within the full query", "name": "stop", "in": "query" }, { "type": "string", - "description": "sortby", + "description": "Sort by either total or sinclair", "name": "sortby", "in": "query" }, { "type": "string", - "description": "federation", + "description": "Federation or country to filter by", "name": "federation", "in": "query" }, { "type": "string", - "description": "weightclass", + "description": "Weightclass to filter by", "name": "weightclass", "in": "query" }, { "type": "integer", - "description": "year", + "description": "Year to filter by", "name": "year", "in": "query" }, { "type": "string", - "description": "startdate", + "description": "Not currently used", "name": "startdate", "in": "query" }, { "type": "string", - "description": "enddate", + "description": "Not currently used", "name": "enddate", "in": "query" } @@ -153,7 +173,7 @@ const docTemplate = `{ }, "/lifter": { "post": { - "description": "do ping", + "description": "This is used within the lifter page to display a lifter's record. It returns a JSON object that can be used with ChartJS without having to do any additional processing.", "consumes": [ "application/json" ], @@ -163,20 +183,34 @@ const docTemplate = `{ "tags": [ "POST Requests" ], - "summary": "how to use the lifter record endpoint", + "summary": "Retrieve a lifter's record for use with ChartJS", + "parameters": [ + { + "description": "name", + "name": "name", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/structs.ChartData" } + }, + "204": { + "description": "No Content" } } } }, "/search": { "get": { - "description": "do ping", + "description": "Looks up a lifter by name and returns a list of possible matches. Requires a minimum of 3 characters.", "consumes": [ "application/json" ], @@ -186,7 +220,16 @@ const docTemplate = `{ "tags": [ "GET Requests" ], - "summary": "how to use the name search endpoint", + "summary": "Search through lifter names", + "parameters": [ + { + "type": "string", + "description": "name", + "name": "name", + "in": "query", + "required": true + } + ], "responses": { "200": { "description": "OK", @@ -367,12 +410,12 @@ const docTemplate = `{ // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ - Version: "", - Host: "", - BasePath: "", - Schemes: []string{}, - Title: "", - Description: "", + Version: "1.0", + Host: "api.openweightlifting.org", + BasePath: "/", + Schemes: []string{"https"}, + Title: "OpenWeightlifting API", + Description: "This is the API for OpenWeightlifting.org", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, LeftDelim: "{{", diff --git a/backend/docs/swagger.json b/backend/docs/swagger.json index ee0937740..1f83cbe34 100644 --- a/backend/docs/swagger.json +++ b/backend/docs/swagger.json @@ -1,12 +1,23 @@ { + "schemes": [ + "https" + ], "swagger": "2.0", "info": { - "contact": {} + "description": "This is the API for OpenWeightlifting.org", + "title": "OpenWeightlifting API", + "contact": { + "name": "Euan Meston", + "email": "euan@openweightlifting.org" + }, + "version": "1.0" }, + "host": "api.openweightlifting.org", + "basePath": "/", "paths": { "/event": { "post": { - "description": "Requires a case-sensitive event name to be passed to it.", + "description": "Requires a case-sensitive event name to be passed to it. This is still a work in progress.", "consumes": [ "application/json" ], @@ -40,13 +51,16 @@ } } } + }, + "204": { + "description": "No Content" } } } }, "/history": { "post": { - "description": "do ping", + "description": "Pull a lifter's history by name. The name must be an exact match and can be checked using the search endpoint.", "consumes": [ "application/json" ], @@ -56,13 +70,27 @@ "tags": [ "POST Requests" ], - "summary": "how to use the lifter history endpoint", + "summary": "Retrieve a lifter's history", + "parameters": [ + { + "description": "name", + "name": "name", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/structs.LifterHistory" } + }, + "204": { + "description": "No Content" } } } @@ -83,49 +111,49 @@ "parameters": [ { "type": "integer", - "description": "start", + "description": "Position to begin from within the full query", "name": "start", "in": "query" }, { "type": "integer", - "description": "stop", + "description": "Position to stop at within the full query", "name": "stop", "in": "query" }, { "type": "string", - "description": "sortby", + "description": "Sort by either total or sinclair", "name": "sortby", "in": "query" }, { "type": "string", - "description": "federation", + "description": "Federation or country to filter by", "name": "federation", "in": "query" }, { "type": "string", - "description": "weightclass", + "description": "Weightclass to filter by", "name": "weightclass", "in": "query" }, { "type": "integer", - "description": "year", + "description": "Year to filter by", "name": "year", "in": "query" }, { "type": "string", - "description": "startdate", + "description": "Not currently used", "name": "startdate", "in": "query" }, { "type": "string", - "description": "enddate", + "description": "Not currently used", "name": "enddate", "in": "query" } @@ -142,7 +170,7 @@ }, "/lifter": { "post": { - "description": "do ping", + "description": "This is used within the lifter page to display a lifter's record. It returns a JSON object that can be used with ChartJS without having to do any additional processing.", "consumes": [ "application/json" ], @@ -152,20 +180,34 @@ "tags": [ "POST Requests" ], - "summary": "how to use the lifter record endpoint", + "summary": "Retrieve a lifter's record for use with ChartJS", + "parameters": [ + { + "description": "name", + "name": "name", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/structs.ChartData" } + }, + "204": { + "description": "No Content" } } } }, "/search": { "get": { - "description": "do ping", + "description": "Looks up a lifter by name and returns a list of possible matches. Requires a minimum of 3 characters.", "consumes": [ "application/json" ], @@ -175,7 +217,16 @@ "tags": [ "GET Requests" ], - "summary": "how to use the name search endpoint", + "summary": "Search through lifter names", + "parameters": [ + { + "type": "string", + "description": "name", + "name": "name", + "in": "query", + "required": true + } + ], "responses": { "200": { "description": "OK", diff --git a/backend/docs/swagger.yaml b/backend/docs/swagger.yaml index 9be059146..36ac42049 100644 --- a/backend/docs/swagger.yaml +++ b/backend/docs/swagger.yaml @@ -1,3 +1,4 @@ +basePath: / definitions: structs.ChartData: properties: @@ -92,14 +93,21 @@ definitions: type: string type: array type: object +host: api.openweightlifting.org info: - contact: {} + contact: + email: euan@openweightlifting.org + name: Euan Meston + description: This is the API for OpenWeightlifting.org + title: OpenWeightlifting API + version: "1.0" paths: /event: post: consumes: - application/json - description: Requires a case-sensitive event name to be passed to it. + description: Requires a case-sensitive event name to be passed to it. This is + still a work in progress. parameters: - description: name in: body @@ -118,6 +126,8 @@ paths: $ref: '#/definitions/structs.Entry' type: array type: array + "204": + description: No Content summary: Pull a specific event by name tags: - POST Requests @@ -125,7 +135,15 @@ paths: post: consumes: - application/json - description: do ping + description: Pull a lifter's history by name. The name must be an exact match + and can be checked using the search endpoint. + parameters: + - description: name + in: body + name: name + required: true + schema: + type: string produces: - application/json responses: @@ -133,7 +151,9 @@ paths: description: OK schema: $ref: '#/definitions/structs.LifterHistory' - summary: how to use the lifter history endpoint + "204": + description: No Content + summary: Retrieve a lifter's history tags: - POST Requests /leaderboard: @@ -143,35 +163,35 @@ paths: description: This is the used on the index page of the website and pulls the highest single lift for a lifter within the selected filter. parameters: - - description: start + - description: Position to begin from within the full query in: query name: start type: integer - - description: stop + - description: Position to stop at within the full query in: query name: stop type: integer - - description: sortby + - description: Sort by either total or sinclair in: query name: sortby type: string - - description: federation + - description: Federation or country to filter by in: query name: federation type: string - - description: weightclass + - description: Weightclass to filter by in: query name: weightclass type: string - - description: year + - description: Year to filter by in: query name: year type: integer - - description: startdate + - description: Not currently used in: query name: startdate type: string - - description: enddate + - description: Not currently used in: query name: enddate type: string @@ -189,7 +209,16 @@ paths: post: consumes: - application/json - description: do ping + description: This is used within the lifter page to display a lifter's record. + It returns a JSON object that can be used with ChartJS without having to do + any additional processing. + parameters: + - description: name + in: body + name: name + required: true + schema: + type: string produces: - application/json responses: @@ -197,14 +226,23 @@ paths: description: OK schema: $ref: '#/definitions/structs.ChartData' - summary: how to use the lifter record endpoint + "204": + description: No Content + summary: Retrieve a lifter's record for use with ChartJS tags: - POST Requests /search: get: consumes: - application/json - description: do ping + description: Looks up a lifter by name and returns a list of possible matches. + Requires a minimum of 3 characters. + parameters: + - description: name + in: query + name: name + required: true + type: string produces: - application/json responses: @@ -212,7 +250,7 @@ paths: description: OK schema: $ref: '#/definitions/structs.NameSearchResults' - summary: how to use the name search endpoint + summary: Search through lifter names tags: - GET Requests /time: @@ -228,4 +266,6 @@ paths: summary: Checking the servers localtime tags: - Utilities and Testing +schemes: +- https swagger: "2.0" diff --git a/backend/endpoints.go b/backend/endpoints.go index a99b62646..1b519ea1d 100644 --- a/backend/endpoints.go +++ b/backend/endpoints.go @@ -39,14 +39,15 @@ func ServerTime(c *gin.Context) { // SearchName godoc // -// @Summary how to use the name search endpoint -// @Schemes -// @Description do ping -// @Tags GET Requests -// @Accept json -// @Produce json -// @Success 200 {object} structs.NameSearchResults -// @Router /search [get] +// @Summary Search through lifter names +// @Schemes +// @Description Looks up a lifter by name and returns a list of possible matches. Requires a minimum of 3 characters. +// @Tags GET Requests +// @Param name query string true "name" +// @Accept json +// @Produce json +// @Success 200 {object} structs.NameSearchResults +// @Router /search [get] func SearchName(c *gin.Context) { const maxResults = 50 if len(c.Query("name")) >= 3 { @@ -64,12 +65,13 @@ func SearchName(c *gin.Context) { // // @Summary Pull a specific event by name // @Schemes -// @Description Requires a case-sensitive event name to be passed to it. +// @Description Requires a case-sensitive event name to be passed to it. This is still a work in progress. // @Tags POST Requests // @Param name body string true "name" // @Accept json // @Produce json // @Success 200 {array} []structs.Entry +// @Failure 204 {object} nil // @Router /event [post] func EventResult(c *gin.Context) { eventSearch := structs.NameSearch{} @@ -86,14 +88,16 @@ func EventResult(c *gin.Context) { // LifterRecord godoc // -// @Summary how to use the lifter record endpoint -// @Schemes -// @Description do ping -// @Tags POST Requests -// @Accept json -// @Produce json -// @Success 200 {object} structs.ChartData -// @Router /lifter [post] +// @Summary Retrieve a lifter's record for use with ChartJS +// @Schemes +// @Description This is used within the lifter page to display a lifter's record. It returns a JSON object that can be used with ChartJS without having to do any additional processing. +// @Tags POST Requests +// @Param name body string true "name" +// @Accept json +// @Produce json +// @Success 200 {object} structs.ChartData +// @Failure 204 {object} nil +// @Router /lifter [post] func LifterRecord(c *gin.Context) { lifterSearch := structs.NameSearch{} if err := c.BindJSON(&lifterSearch); err != nil { @@ -112,14 +116,16 @@ func LifterRecord(c *gin.Context) { // LifterHistory godoc // -// @Summary how to use the lifter history endpoint -// @Schemes -// @Description do ping -// @Tags POST Requests -// @Accept json -// @Produce json -// @Success 200 {object} structs.LifterHistory -// @Router /history [post] +// @Summary Retrieve a lifter's history +// @Schemes +// @Description Pull a lifter's history by name. The name must be an exact match and can be checked using the search endpoint. +// @Tags POST Requests +// @Param name body string true "name" +// @Accept json +// @Produce json +// @Success 200 {object} structs.LifterHistory +// @Failure 204 {object} nil +// @Router /history [post] func LifterHistory(c *gin.Context) { lifterSearch := structs.NameSearch{} if err := c.BindJSON(&lifterSearch); err != nil { @@ -144,14 +150,14 @@ func LifterHistory(c *gin.Context) { // @Description This is the used on the index page of the website and pulls the highest single lift for a lifter within the selected filter. // @Tags POST Requests // -// @Param start query int false "start" -// @Param stop query int false "stop" -// @Param sortby query string false "sortby" -// @Param federation query string false "federation" -// @Param weightclass query string false "weightclass" -// @Param year query int false "year" -// @Param startdate query string false "startdate" -// @Param enddate query string false "enddate" +// @Param start query int false "Position to begin from within the full query" +// @Param stop query int false "Position to stop at within the full query" +// @Param sortby query string false "Sort by either total or sinclair" +// @Param federation query string false "Federation or country to filter by" +// @Param weightclass query string false "Weightclass to filter by" +// @Param year query int false "Year to filter by" +// @Param startdate query string false "Not currently used" +// @Param enddate query string false "Not currently used" // // @Accept json // @Produce json diff --git a/backend/main.go b/backend/main.go index 60f20c338..2a867a222 100644 --- a/backend/main.go +++ b/backend/main.go @@ -2,8 +2,11 @@ package main import ( "backend/dbtools" + docs "github.com/euanwm/OpenWeightlifting/backend/docs" "github.com/gin-contrib/cors" "github.com/gin-gonic/gin" + swaggerFiles "github.com/swaggo/files" + ginSwagger "github.com/swaggo/gin-swagger" "log" "os" ) @@ -35,7 +38,7 @@ func buildServer() *gin.Engine { log.Println("Starting server...") dbtools.BuildDatabase(&processedLeaderboard) r := gin.Default() - // docs.SwaggerInfo.BasePath = "/" + docs.SwaggerInfo.BasePath = "/" setupCORS(r) r.GET("time", ServerTime) r.POST("leaderboard", Leaderboard) @@ -43,7 +46,7 @@ func buildServer() *gin.Engine { r.POST("lifter", LifterRecord) r.POST("history", LifterHistory) r.POST("event", EventResult) - // r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) + r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) return r } @@ -59,6 +62,14 @@ func CacheMeOutsideHowBoutDat() { log.Println("Caching complete") } +// @title OpenWeightlifting API +// @description This is the API for OpenWeightlifting.org +// @BasePath / +// @version 1.0 +// @contact.name Euan Meston +// @contact.email euan@openweightlifting.org +// @host api.openweightlifting.org +// @schemes https func main() { apiServer := buildServer() go CacheMeOutsideHowBoutDat()