certusone
/
wormhole-explorer
mirror of https://github.com/certusone/wormhole-explorer.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[API] Increase documentation coverage (#90) 

Add swagger documentation for all endpoints.

This addresses https://github.com/wormhole-foundation/wormhole-explorer/issues/68
This commit is contained in:
agodnic 2023-01-25 16:19:14 -03:00 committed by GitHub
parent cc1f1b440f
commit 6022d5fd14
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 4765 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1722
api/docs/docs.go
View File

File diff suppressed because it is too large Load Diff

1722
api/docs/swagger.json
View File

File diff suppressed because it is too large Load Diff

1139
api/docs/swagger.yaml
View File

File diff suppressed because it is too large Load Diff

151
api/handlers/governor/controller.go
View File

@ -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/
func (c *Controller) GetEnqueueVass(ctx *fiber.Ctx) error {
// GetEnqueueVaas godoc
// @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.
func (c *Controller) GetEnqueueVassByChainID(ctx *fiber.Ctx) error {
// GetEnqueuedVaasByChainID godoc
// @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

17
api/handlers/infraestructure/controller.go → api/handlers/infrastructure/controller.go
View File

@ -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 {

0
api/handlers/infraestructure/model.go → api/handlers/infrastructure/model.go
View File

0
api/handlers/infraestructure/repository.go → api/handlers/infrastructure/repository.go
View File

0
api/handlers/infraestructure/service.go → api/handlers/infrastructure/service.go
View File

60
api/handlers/observations/controller.go
View File

@ -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 {

6
api/main.go
View File

@ -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("/:chain", governorCtrl.GetEnqueueVassByChainID)
enqueueVaas.Get("/", governorCtrl.GetEnqueueVaas)
enqueueVaas.Get("/:chain", governorCtrl.GetEnqueuedVaasByChainID)
// v1 guardian public api.
publicAPIV1 := app.Group("/v1")