From 0d08f0b73eb2a4a4321720b8f0563123ff3ecd8d Mon Sep 17 00:00:00 2001 From: Kieran O'Neill Date: Wed, 12 Jun 2024 11:08:58 +0100 Subject: [PATCH] feat(v1): add better comments --- lib/errors/invalidaddresserror.go | 8 +-- lib/errors/posthogerror.go | 8 +-- lib/errors/requiredparamserror.go | 8 +-- lib/errors/unknownerror.go | 8 +-- .../v1/quests/internal/types/dailyquest.go | 8 ++- .../v1/quests/internal/types/responsebody.go | 8 ++- packages/v1/quests/main.go | 8 ++- packages/v1/swagger/swagger.json | 64 +++++++++++++++---- .../versions/internal/types/responsebody.go | 6 +- packages/v1/versions/main.go | 13 ++-- 10 files changed, 94 insertions(+), 45 deletions(-) diff --git a/lib/errors/invalidaddresserror.go b/lib/errors/invalidaddresserror.go index 8a66c3b..3cae793 100644 --- a/lib/errors/invalidaddresserror.go +++ b/lib/errors/invalidaddresserror.go @@ -6,10 +6,10 @@ import ( ) type InvalidAddressError struct { - Address string - Code int - Message string - Name string + Address string `json:"address"` + Code int `json:"code"` + Message string `json:"message"` + Name string `json:"name"` } func NewInvalidAddressError(address string) *InvalidAddressError { diff --git a/lib/errors/posthogerror.go b/lib/errors/posthogerror.go index 313cc9f..1740e9f 100644 --- a/lib/errors/posthogerror.go +++ b/lib/errors/posthogerror.go @@ -3,10 +3,10 @@ package errors import "lib/constants" type PostHogError struct { - Code int - Error error - Message string - Name string + Code int `json:"code"` + Error error `json:"error"` + Message string `json:"message"` + Name string `json:"name"` } func NewPostHogError(message string, error error) *PostHogError { diff --git a/lib/errors/requiredparamserror.go b/lib/errors/requiredparamserror.go index fa16431..9dc8974 100644 --- a/lib/errors/requiredparamserror.go +++ b/lib/errors/requiredparamserror.go @@ -6,10 +6,10 @@ import ( ) type RequiredParamsError struct { - Code int - Message string - Name string - Params []string + Code int `json:"code"` + Message string `json:"message"` + Name string `json:"name"` + Params []string `json:"params"` } func NewRequiredParamsError(params []string) *RequiredParamsError { diff --git a/lib/errors/unknownerror.go b/lib/errors/unknownerror.go index 3c57376..a8fa8e8 100644 --- a/lib/errors/unknownerror.go +++ b/lib/errors/unknownerror.go @@ -3,10 +3,10 @@ package errors import "lib/constants" type UnknownError struct { - Code int - Error error - Message string - Name string + Code int `json:"code"` + Error error `json:"error"` + Message string `json:"message"` + Name string `json:"name"` } func NewUnknownError(message string, error error) *UnknownError { diff --git a/packages/v1/quests/internal/types/dailyquest.go b/packages/v1/quests/internal/types/dailyquest.go index c58ddfc..1a29107 100644 --- a/packages/v1/quests/internal/types/dailyquest.go +++ b/packages/v1/quests/internal/types/dailyquest.go @@ -1,6 +1,10 @@ package types +// DailyQuest +// @Description The ID of the quest and the amount of times it has been completed. type DailyQuest struct { - Completed int `json:"completed"` - Id string `json:"id"` + // The amount of times the quest has been completed + Completed int `json:"completed" example:"22"` + // The ID of the quest + Id string `json:"id" example:"send-native-currency-action"` } diff --git a/packages/v1/quests/internal/types/responsebody.go b/packages/v1/quests/internal/types/responsebody.go index ca0b3c0..e36b8ac 100644 --- a/packages/v1/quests/internal/types/responsebody.go +++ b/packages/v1/quests/internal/types/responsebody.go @@ -1,7 +1,9 @@ package types type ResponseBody struct { - Account string `json:"account,omitempty"` - Error interface{} `json:"error,omitempty"` - Quests []DailyQuest `json:"quests,omitempty"` + // The account address + Account string `json:"account,omitempty" example:"TESTK4BURRDGVVHAX2FBY7CPRC2RTTVRRN4C2TVDCHRCXNTFGL3TVSDROE"` + Error interface{} `json:"error,omitempty" swaggertype:"object"` + // The completed quests + Quests []DailyQuest `json:"quests,omitempty"` } diff --git a/packages/v1/quests/main.go b/packages/v1/quests/main.go index ed647a8..3e716ec 100644 --- a/packages/v1/quests/main.go +++ b/packages/v1/quests/main.go @@ -18,9 +18,11 @@ import ( // @Produce json // @Param account query string true "account to get daily quests" Example(TESTK4BURRDGVVHAX2FBY7CPRC2RTTVRRN4C2TVDCHRCXNTFGL3TVSDROE) // @Success 200 {object} _types.ResponseBody -// @failure 400 {object} _types.ResponseBody "if the account param is not provided or invalid" -// @failure 405 {object} _types.ResponseBody "will return if it is not a GET request" -// @failure 500 {object} _types.ResponseBody +// @Failure 400 "If the account param is not provided" +// @Failure 400 "If the account param is an invalid AVM address" +// @Failure 405 "If it is not a GET or OPTIONS request" +// @Failure 500 +// @Header all {string} Cache-Control "public, max-age=3600" // @Router /v1/quests [get] func Main(request _types.Request) *_types.Response { var dailyQuests []_types.DailyQuest diff --git a/packages/v1/swagger/swagger.json b/packages/v1/swagger/swagger.json index 17a605a..6576344 100644 --- a/packages/v1/swagger/swagger.json +++ b/packages/v1/swagger/swagger.json @@ -36,22 +36,40 @@ "description": "OK", "schema": { "$ref": "#/definitions/quests_internal_types.ResponseBody" + }, + "headers": { + "Cache-Control": { + "type": "string", + "description": "public, max-age=3600" + } } }, "400": { - "description": "if the account param is not provided or invalid", - "schema": { - "$ref": "#/definitions/quests_internal_types.ResponseBody" + "description": "If the account param is an invalid AVM address", + "headers": { + "Cache-Control": { + "type": "string", + "description": "public, max-age=3600" + } } }, "405": { - "description": "will return if it is not a GET request", - "schema": { - "$ref": "#/definitions/quests_internal_types.ResponseBody" + "description": "If it is not a GET or OPTIONS request", + "headers": { + "Cache-Control": { + "type": "string", + "description": "public, max-age=3600" + } } }, "500": { - "description": "Internal Server Error" + "description": "Internal Server Error", + "headers": { + "Cache-Control": { + "type": "string", + "description": "public, max-age=3600" + } + } } } } @@ -68,6 +86,12 @@ "description": "OK", "schema": { "$ref": "#/definitions/versions_internal_types.ResponseBody" + }, + "headers": { + "Cache-Control": { + "type": "string", + "description": "public, max-age=604800" + } } } } @@ -79,10 +103,15 @@ "type": "object", "properties": { "account": { - "type": "string" + "description": "The account address", + "type": "string", + "example": "TESTK4BURRDGVVHAX2FBY7CPRC2RTTVRRN4C2TVDCHRCXNTFGL3TVSDROE" + }, + "error": { + "type": "object" }, - "error": {}, "quests": { + "description": "The completed quests", "type": "array", "items": { "$ref": "#/definitions/types.DailyQuest" @@ -91,13 +120,18 @@ } }, "types.DailyQuest": { + "description": "The ID of the quest and the amount of times it has been completed.", "type": "object", "properties": { "completed": { - "type": "integer" + "description": "The amount of times the quest has been completed", + "type": "integer", + "example": 22 }, "id": { - "type": "string" + "description": "The ID of the quest", + "type": "string", + "example": "send-native-currency-action" } } }, @@ -105,10 +139,14 @@ "type": "object", "properties": { "apiVersion": { - "type": "string" + "description": "The semantic version of the API", + "type": "string", + "example": "1.1.0" }, "environment": { - "type": "string" + "description": "The API environment", + "type": "string", + "example": "production" } } } diff --git a/packages/v1/versions/internal/types/responsebody.go b/packages/v1/versions/internal/types/responsebody.go index 0e1fb27..4facc9b 100644 --- a/packages/v1/versions/internal/types/responsebody.go +++ b/packages/v1/versions/internal/types/responsebody.go @@ -1,6 +1,8 @@ package types type ResponseBody struct { - APIVersion string `json:"apiVersion"` - Environment string `json:"environment"` + // The semantic version of the API + APIVersion string `json:"apiVersion" example:"1.1.0"` + // The API environment + Environment string `json:"environment" example:"production"` } diff --git a/packages/v1/versions/main.go b/packages/v1/versions/main.go index d227264..8030761 100644 --- a/packages/v1/versions/main.go +++ b/packages/v1/versions/main.go @@ -13,12 +13,13 @@ import ( //go:embed VERSION var version string -// Main godoc. -// @Summary API Information -// @Description Gets API information including the environment and version. -// @Produce json -// @Success 200 {object} _types.ResponseBody -// @Router /v1/versions [get] +// Main godoc +// @summary API Information +// @description Gets API information including the environment and version. +// @produce json +// @success 200 {object} _types.ResponseBody +// @header all {string} Cache-Control "public, max-age=604800" +// @router /v1/versions [get] func Main() *_types.Response { return &_types.Response{ Body: _types.ResponseBody{