[API] Increase documentation coverage (#90)

Add swagger documentation for all endpoints.

This addresses https://github.com/wormhole-foundation/wormhole-explorer/issues/68

api/handlers/governor/controller.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/gofiber/fiber/v2"
 	"github.com/wormhole-foundation/wormhole-explorer/api/middleware"
+	_ "github.com/wormhole-foundation/wormhole-explorer/api/response" // needed by swaggo docs
 	"github.com/wormhole-foundation/wormhole/sdk/vaa"
 	"go.uber.org/zap"
 )
@@ -21,7 +22,17 @@ func NewController(serv *Service, logger *zap.Logger) *Controller {
 	return &Controller{srv: serv, logger: logger.With(zap.String("module", "GovernorController"))}
 }
 
-// FindGovernorConfigurations handler for the endpoint /governor/config/
+// FindGovernorConfigurations godoc
+// @Description Returns governor configuration for all guardians.
+// @Tags Wormscan
+// @ID governor-config
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[GovConfig]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/config [get]
 func (c *Controller) FindGovernorConfigurations(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	governorConfigs, err := c.srv.FindGovernorConfig(ctx.Context(), p)
@@ -31,7 +42,17 @@ func (c *Controller) FindGovernorConfigurations(ctx *fiber.Ctx) error {
 	return ctx.JSON(governorConfigs)
 }
 
-// FindGovernorConfigurationByGuardianAddress handler for the endpoint /governor/config/:guardian_address.
+// FindGovernorConfigurationByGuardianAddress godoc
+// @Description Returns governor configuration for a given guardian.
+// @Tags Wormscan
+// @ID governor-config-by-guardian-address
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]GovConfig]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/config/:guardian_address [get]
 func (c *Controller) FindGovernorConfigurationByGuardianAddress(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	guardianAddress, err := middleware.ExtractGuardianAddress(ctx, c.logger)
@@ -45,7 +66,17 @@ func (c *Controller) FindGovernorConfigurationByGuardianAddress(ctx *fiber.Ctx)
 	return ctx.JSON(govConfig)
 }
 
-// FindGovernorStatus handler for the endpoint /governor/status/.
+// FindGovernorStatus godoc
+// @Description Returns the governor status for all guardians.
+// @Tags Wormscan
+// @ID governor-status
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]GovStatus]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/status [get]
 func (c *Controller) FindGovernorStatus(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	governorStatus, err := c.srv.FindGovernorStatus(ctx.Context(), p)
@@ -55,7 +86,17 @@ func (c *Controller) FindGovernorStatus(ctx *fiber.Ctx) error {
 	return ctx.JSON(governorStatus)
 }
 
-// FindGovernorStatusByGuardianAddress handler for the endpoint /governor/status/:guardian_address.
+// FindGovernorStatusByGuardianAddress godoc
+// @Description Returns the governor status for a given guardian.
+// @Tags Wormscan
+// @ID governor-status-by-guardian-address
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[GovStatus]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/status/:guardian_address [get]
 func (c *Controller) FindGovernorStatusByGuardianAddress(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	guardianAddress, err := middleware.ExtractGuardianAddress(ctx, c.logger)
@@ -69,7 +110,17 @@ func (c *Controller) FindGovernorStatusByGuardianAddress(ctx *fiber.Ctx) error {
 	return ctx.JSON(govStatus)
 }
 
-// GetGovernorLimit handler for the endpoint /governor/limit/
+// GetGovernorLimit godoc
+// @Description Returns the governor limit for all blockchains.
+// @Tags Wormscan
+// @ID governor-notional-limit
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]GovernorLimit]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/limit [get]
 func (c *Controller) GetGovernorLimit(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	governorLimit, err := c.srv.GetGovernorLimit(ctx.Context(), p)
@@ -79,7 +130,17 @@ func (c *Controller) GetGovernorLimit(ctx *fiber.Ctx) error {
 	return ctx.JSON(governorLimit)
 }
 
-// FindNotionalLimit handler for the endpoint governor/notional/limit/
+// FindNotionalLimit godoc
+// @Description Returns the detailed notional limit for all blockchains.
+// @Tags Wormscan
+// @ID governor-notional-limit-detail
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]NotionalLimitDetail]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/notional/limit [get]
 func (c *Controller) FindNotionalLimit(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	notionalLimit, err := c.srv.FindNotionalLimit(ctx.Context(), p)
@@ -89,7 +150,17 @@ func (c *Controller) FindNotionalLimit(ctx *fiber.Ctx) error {
 	return ctx.JSON(notionalLimit)
 }
 
-// GetNotionalLimitByChainID handler for the endpoint governor/notional/limit/:chain.
+// GetNotionalLimitByChainID godoc
+// @Description Returns the detailed notional limit available for a given blockchain.
+// @Tags Wormscan
+// @ID governor-notional-limit-detail-by-chain
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]NotionalLimitDetail]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/notional/limit/:chain [get]
 func (c *Controller) GetNotionalLimitByChainID(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, err := middleware.ExtractChainID(ctx, c.logger)
@@ -103,7 +174,17 @@ func (c *Controller) GetNotionalLimitByChainID(ctx *fiber.Ctx) error {
 	return ctx.JSON(notionalLimit)
 }
 
-// GetAvailableNotional handler for the endpoint governor/notional/available/
+// GetAvailableNotional godoc
+// @Description Returns the amount of notional value available for each blockchain.
+// @Tags Wormscan
+// @ID governor-notional-available
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]NotionalAvailable]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/notional/available [get]
 func (c *Controller) GetAvailableNotional(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	notionalAvaialabilies, err := c.srv.GetAvailableNotional(ctx.Context(), p)
@@ -113,7 +194,17 @@ func (c *Controller) GetAvailableNotional(ctx *fiber.Ctx) error {
 	return ctx.JSON(notionalAvaialabilies)
 }
 
-// GetAvailableNotionalByChainID handler for the endpoint governor/notional/available/:chain
+// GetAvailableNotionalByChainID godoc
+// @Description Returns the amount of notional value available for a given blockchain.
+// @Tags Wormscan
+// @ID governor-notional-available-by-chain
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]NotionalAvailableDetail]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/notional/available/:chain [get]
 func (c *Controller) GetAvailableNotionalByChainID(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, err := middleware.ExtractChainID(ctx, c.logger)
@@ -127,7 +218,17 @@ func (c *Controller) GetAvailableNotionalByChainID(ctx *fiber.Ctx) error {
 	return ctx.JSON(response)
 }
 
-// GetMaxNotionalAvailableByChainID handler for the endpoint governor/max_available/:chain.
+// GetMaxNotionalAvailableByChainID godoc
+// @Description Returns the maximum amount of notional value available for a given blockchain.
+// @Tags Wormscan
+// @ID governor-max-notional-available-by-chain
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[MaxNotionalAvailableRecord]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/max_available/:chain [get]
 func (c *Controller) GetMaxNotionalAvailableByChainID(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, err := middleware.ExtractChainID(ctx, c.logger)
@@ -141,8 +242,18 @@ func (c *Controller) GetMaxNotionalAvailableByChainID(ctx *fiber.Ctx) error {
 	return ctx.JSON(response)
 }
 
-// GetEnqueueVass handler for the endpoint governor/enqueued_vaas/
+// GetEnqueueVaas godoc
-func (c *Controller) GetEnqueueVass(ctx *fiber.Ctx) error {
+// @Description Returns enqueued VAAs for each blockchain.
+// @Tags Wormscan
+// @ID governor-enqueued-vaas
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]EnqueuedVaas]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/enqueued_vaas/ [get]
+func (c *Controller) GetEnqueueVaas(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	enqueuedVaas, err := c.srv.GetEnqueueVass(ctx.Context(), p)
 	if err != nil {
@@ -151,8 +262,18 @@ func (c *Controller) GetEnqueueVass(ctx *fiber.Ctx) error {
 	return ctx.JSON(enqueuedVaas)
 }
 
-// GetEnqueueVassByChainID handler for the endpoint governor/enqueued_vaas/:chain.
+// GetEnqueuedVaasByChainID godoc
-func (c *Controller) GetEnqueueVassByChainID(ctx *fiber.Ctx) error {
+// @Description Returns all enqueued VAAs for a given blockchain.
+// @Tags Wormscan
+// @ID guardians-enqueued-vaas-by-chain
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} response.Response[[]EnqueuedVaaDetail]
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/governor/enqueued_vaas/:chain [get]
+func (c *Controller) GetEnqueuedVaasByChainID(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, err := middleware.ExtractChainID(ctx, c.logger)
 	if err != nil {
@@ -228,7 +349,7 @@ type EnqueuedVaaItemResponse struct {
 }
 
 // GetEnqueuedVaas godoc
-// @Description Get enqueued vaa's
+// @Description Get enqueued VAAs
 // @Tags Guardian
 // @ID guardians-enqueued-vaas
 // @Success 200 {object} EnqueuedVaaResponse

api/handlers/infrastructure/controller.go

@@ -12,7 +12,14 @@ func NewController(serv *Service) *Controller {
 	return &Controller{srv: serv}
 }
 
-// HealthCheck handler for the endpoint /health.
+// HealthCheck godoc
+// @Description Health check
+// @Tags Wormscan
+// @ID health-check
+// @Success 200 {object} object{status=string}
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/health [get]
 func (c *Controller) HealthCheck(ctx *fiber.Ctx) error {
 	return ctx.JSON(struct {
 		Status string `json:"status"`
@@ -20,6 +27,14 @@ func (c *Controller) HealthCheck(ctx *fiber.Ctx) error {
 }
 
 // ReadyCheck handler for the endpoint /ready
+// ReadyCheck godoc
+// @Description Ready check
+// @Tags Wormscan
+// @ID ready-check
+// @Success 200 {object} object{status=string}
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/ready [get]
 func (c *Controller) ReadyCheck(ctx *fiber.Ctx) error {
 	ready, _ := c.srv.CheckMongoServerStatus(ctx.Context())
 	if ready {

api/handlers/observations/controller.go

@@ -23,7 +23,17 @@ func NewController(srv *Service, logger *zap.Logger) *Controller {
 	}
 }
 
-// FindAll handler for the endpoint /observations/.
+// FindAll godoc
+// @Description Returns all observations.
+// @Tags Wormscan
+// @ID find-observations
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} []ObservationDoc
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/observations [get]
 func (c *Controller) FindAll(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	obs, err := c.srv.FindAll(ctx.Context(), p)
@@ -33,7 +43,17 @@ func (c *Controller) FindAll(ctx *fiber.Ctx) error {
 	return ctx.JSON(obs)
 }
 
-// FindAllByChain handler for the endpoint /observations/:chain.
+// FindAllByChain godoc
+// @Description Returns all observations for a given blockchain.
+// @Tags Wormscan
+// @ID find-observations-by-chain
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} []ObservationDoc
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/observations/:chain [get]
 func (c *Controller) FindAllByChain(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, err := middleware.ExtractChainID(ctx, c.logger)
@@ -47,7 +67,17 @@ func (c *Controller) FindAllByChain(ctx *fiber.Ctx) error {
 	return ctx.JSON(obs)
 }
 
-// FindAllByEmitter handler for the endpoint /observations/:chain/:emitter.
+// FindAllByEmitter godoc
+// @Description Returns all observations for a specific emitter address.
+// @Tags Wormscan
+// @ID find-observations-by-emitter
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} []ObservationDoc
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/observations/:chain/:emitter [get]
 func (c *Controller) FindAllByEmitter(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, addr, err := middleware.ExtractVAAChainIDEmitter(ctx, c.logger)
@@ -62,7 +92,17 @@ func (c *Controller) FindAllByEmitter(ctx *fiber.Ctx) error {
 	return ctx.JSON(obs)
 }
 
-// FindAllByVAA handler for the endpoint  /observations/:chain/:emitter/:sequence
+// FindAllByVAA godoc
+// @Description Find observations identified by emitter chain, emitter address and sequence.
+// @Tags Wormscan
+// @ID find-observations-by-sequence
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} []ObservationDoc
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/observations/:chain/:emitter/:sequence [get]
 func (c *Controller) FindAllByVAA(ctx *fiber.Ctx) error {
 	p := middleware.GetPaginationFromContext(ctx)
 	chainID, addr, seq, err := middleware.ExtractVAAParams(ctx, c.logger)
@@ -77,7 +117,17 @@ func (c *Controller) FindAllByVAA(ctx *fiber.Ctx) error {
 	return ctx.JSON(obs)
 }
 
-// FindOne handler for the endpoint /observations/:chain/:emitter/:sequence/:signer/:hash
+// FindOne godoc
+// @Description Find a specific observation.
+// @Tags Wormscan
+// @ID find-observations-by-id
+// @Param page query integer false "Page number."
+// @Param pageSize query integer false "Number of elements per page."
+// @Param sortOrder query string false "Sort results in ascending or descending order." Enums(ASC, DESC)
+// @Success 200 {object} []ObservationDoc
+// @Failure 400
+// @Failure 500
+// @Router /api/v1/observations/:chain/:emitter/:sequence/:signer/:hash [get]
 func (c *Controller) FindOne(ctx *fiber.Ctx) error {
 	chainID, addr, seq, err := middleware.ExtractVAAParams(ctx, c.logger)
 	if err != nil {

api/main.go

@@ -21,7 +21,7 @@ import (
 	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/governor"
 	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/guardian"
 	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/heartbeats"
-	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/infraestructure"
+	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/infrastructure"
 	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/observations"
 	"github.com/wormhole-foundation/wormhole-explorer/api/handlers/vaa"
 	wormscanCache "github.com/wormhole-foundation/wormhole-explorer/api/internal/cache"
@@ -171,8 +171,8 @@ func main() {
 	governorNotional.Get("/max_available/:chain", governorCtrl.GetMaxNotionalAvailableByChainID)
 
 	enqueueVaas := governor.Group("/enqueued_vaas")
-	enqueueVaas.Get("/", governorCtrl.GetEnqueueVass)
+	enqueueVaas.Get("/", governorCtrl.GetEnqueueVaas)
-	enqueueVaas.Get("/:chain", governorCtrl.GetEnqueueVassByChainID)
+	enqueueVaas.Get("/:chain", governorCtrl.GetEnqueuedVaasByChainID)
 
 	// v1 guardian public api.
 	publicAPIV1 := app.Group("/v1")