feat(v1): add better comments

kibis-is · Jun 12, 2024 · 0d08f0b · 0d08f0b
1 parent 11b187a
commit 0d08f0b
Show file tree

Hide file tree

Showing 10 changed files with 94 additions and 45 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,24 +120,33 @@
             }
         },
         "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"
                 }
             }
         },
         "versions_internal_types.ResponseBody": {
             "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
@@ -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
@@ -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{