diff --git a/Makefile b/Makefile index f69ef3e..db13c7f 100644 --- a/Makefile +++ b/Makefile @@ -11,6 +11,7 @@ build: ${BUILD_CONF} go build -ldflags="-X main.build=${BUILD_COMMIT} -s -w" -o ${BIN} cmd/service/* docs: + swag fmt --dir internal/api/ swag init --dir internal/api/ -g swagger.go run: diff --git a/config.toml b/config.toml index db6cb35..c57d4f2 100644 --- a/config.toml +++ b/config.toml @@ -3,7 +3,7 @@ address = ":5000" # Exposes Go process Prometheus metrics # /metrics endpoint metrics = true -docs = true +docs = false [chain] rpc_endpoint = "" diff --git a/docs/docs.go b/docs/docs.go index 54b60a6..c2a4b69 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -25,7 +25,7 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { - "/": { + "/account/create": { "post": { "description": "Create a new custodial account.", "consumes": [ @@ -34,17 +34,201 @@ const docTemplate = `{ "produces": [ "application/json" ], + "tags": [ + "account" + ], "summary": "Create a new custodial account.", "responses": { "200": { "description": "OK", "schema": { - "type": "object", - "additionalProperties": true + "$ref": "#/definitions/api.OkResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" } } } } + }, + "/account/status/{address}": { + "get": { + "description": "Return network balance and nonce.", + "consumes": [ + "*/*" + ], + "produces": [ + "application/json" + ], + "tags": [ + "network" + ], + "summary": "Get an address's network balance and nonce.", + "parameters": [ + { + "type": "string", + "description": "Account Public Key", + "name": "address", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + }, + "/sign/transfer": { + "post": { + "description": "Sign and dispatch a transfer request.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "network" + ], + "summary": "Sign and dispatch transfer request.", + "parameters": [ + { + "description": "Sign Transfer Request", + "name": "signTransferRequest", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + }, + "voucherAddress": { + "type": "string" + } + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + }, + "/track/{trackingId}": { + "get": { + "description": "Track an OTX (Origin transaction) status.", + "consumes": [ + "*/*" + ], + "produces": [ + "application/json" + ], + "tags": [ + "track" + ], + "summary": "Track an OTX (Origin transaction) status.", + "parameters": [ + { + "type": "string", + "description": "Tracking Id", + "name": "trackingId", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + } + }, + "definitions": { + "api.ErrResp": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "ok": { + "type": "boolean" + } + } + }, + "api.H": { + "type": "object", + "additionalProperties": {} + }, + "api.OkResp": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "result": { + "$ref": "#/definitions/api.H" + } + } } } }` diff --git a/docs/swagger.json b/docs/swagger.json index 1a20d82..03bcfcf 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -17,7 +17,7 @@ }, "basePath": "/api", "paths": { - "/": { + "/account/create": { "post": { "description": "Create a new custodial account.", "consumes": [ @@ -26,17 +26,201 @@ "produces": [ "application/json" ], + "tags": [ + "account" + ], "summary": "Create a new custodial account.", "responses": { "200": { "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + }, + "/account/status/{address}": { + "get": { + "description": "Return network balance and nonce.", + "consumes": [ + "*/*" + ], + "produces": [ + "application/json" + ], + "tags": [ + "network" + ], + "summary": "Get an address's network balance and nonce.", + "parameters": [ + { + "type": "string", + "description": "Account Public Key", + "name": "address", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + }, + "/sign/transfer": { + "post": { + "description": "Sign and dispatch a transfer request.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "network" + ], + "summary": "Sign and dispatch transfer request.", + "parameters": [ + { + "description": "Sign Transfer Request", + "name": "signTransferRequest", + "in": "body", + "required": true, "schema": { "type": "object", - "additionalProperties": true + "properties": { + "amount": { + "type": "integer" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + }, + "voucherAddress": { + "type": "string" + } + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + } + } + } + }, + "/track/{trackingId}": { + "get": { + "description": "Track an OTX (Origin transaction) status.", + "consumes": [ + "*/*" + ], + "produces": [ + "application/json" + ], + "tags": [ + "track" + ], + "summary": "Track an OTX (Origin transaction) status.", + "parameters": [ + { + "type": "string", + "description": "Tracking Id", + "name": "trackingId", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.OkResp" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.ErrResp" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrResp" } } } } } + }, + "definitions": { + "api.ErrResp": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "ok": { + "type": "boolean" + } + } + }, + "api.H": { + "type": "object", + "additionalProperties": {} + }, + "api.OkResp": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "result": { + "$ref": "#/definitions/api.H" + } + } + } } } \ No newline at end of file diff --git a/docs/swagger.yaml b/docs/swagger.yaml index d1ae5f5..56f98f6 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1,4 +1,22 @@ basePath: /api +definitions: + api.ErrResp: + properties: + message: + type: string + ok: + type: boolean + type: object + api.H: + additionalProperties: {} + type: object + api.OkResp: + properties: + ok: + type: boolean + result: + $ref: '#/definitions/api.H' + type: object info: contact: email: devops@grassecon.org @@ -12,7 +30,7 @@ info: title: CIC Custodial API version: "1.0" paths: - /: + /account/create: post: consumes: - '*/*' @@ -23,7 +41,109 @@ paths: "200": description: OK schema: - additionalProperties: true - type: object + $ref: '#/definitions/api.OkResp' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrResp' summary: Create a new custodial account. + tags: + - account + /account/status/{address}: + get: + consumes: + - '*/*' + description: Return network balance and nonce. + parameters: + - description: Account Public Key + in: path + name: address + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.OkResp' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.ErrResp' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrResp' + summary: Get an address's network balance and nonce. + tags: + - network + /sign/transfer: + post: + consumes: + - application/json + description: Sign and dispatch a transfer request. + parameters: + - description: Sign Transfer Request + in: body + name: signTransferRequest + required: true + schema: + properties: + amount: + type: integer + from: + type: string + to: + type: string + voucherAddress: + type: string + type: object + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.OkResp' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.ErrResp' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrResp' + summary: Sign and dispatch transfer request. + tags: + - network + /track/{trackingId}: + get: + consumes: + - '*/*' + description: Track an OTX (Origin transaction) status. + parameters: + - description: Tracking Id + in: path + name: trackingId + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.OkResp' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.ErrResp' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrResp' + summary: Track an OTX (Origin transaction) status. + tags: + - track swagger: "2.0" diff --git a/internal/api/account.go b/internal/api/account.go index 269951f..1235fe2 100644 --- a/internal/api/account.go +++ b/internal/api/account.go @@ -13,12 +13,14 @@ import ( ) // HandleAccountCreate godoc -// @Summary Create a new custodial account. -// @Description Create a new custodial account. -// @Accept */* -// @Produce json -// @Success 200 {object} map[string]interface{} -// @Router / [post] +// @Summary Create a new custodial account. +// @Description Create a new custodial account. +// @Tags account +// @Accept */* +// @Produce json +// @Success 200 {object} OkResp +// @Failure 500 {object} ErrResp +// @Router /account/create [post] func HandleAccountCreate(cu *custodial.Custodial) func(echo.Context) error { return func(c echo.Context) error { generatedKeyPair, err := keypair.Generate() diff --git a/internal/api/network.go b/internal/api/network.go index eb502ef..7152aaf 100644 --- a/internal/api/network.go +++ b/internal/api/network.go @@ -12,6 +12,17 @@ import ( "github.com/labstack/echo/v4" ) +// HandleNetworkAccountStatus godoc +// @Summary Get an address's network balance and nonce. +// @Description Return network balance and nonce. +// @Tags network +// @Accept */* +// @Produce json +// @Param address path string true "Account Public Key" +// @Success 200 {object} OkResp +// @Failure 400 {object} ErrResp +// @Failure 500 {object} ErrResp +// @Router /account/status/{address} [get] func HandleNetworkAccountStatus(cu *custodial.Custodial) func(echo.Context) error { return func(c echo.Context) error { var ( diff --git a/internal/api/sign.go b/internal/api/sign.go index 8cb9958..081d02c 100644 --- a/internal/api/sign.go +++ b/internal/api/sign.go @@ -12,15 +12,17 @@ import ( "github.com/labstack/echo/v4" ) -// HandleSignTransfer route. -// POST: /api/sign/transfer -// JSON Body: -// from -> ETH address -// to -> ETH address -// voucherAddress -> ETH address -// amount -> int (6 d.p. precision) -// e.g. 1000000 = 1 VOUCHER -// Returns the task id. +// HandleSignTransfer godoc +// @Summary Sign and dispatch transfer request. +// @Description Sign and dispatch a transfer request. +// @Tags network +// @Accept json +// @Produce json +// @Param signTransferRequest body object{from=string,to=string,voucherAddress=string,amount=uint64} true "Sign Transfer Request" +// @Success 200 {object} OkResp +// @Failure 400 {object} ErrResp +// @Failure 500 {object} ErrResp +// @Router /sign/transfer [post] func HandleSignTransfer(cu *custodial.Custodial) func(echo.Context) error { return func(c echo.Context) error { var ( diff --git a/internal/api/swagger.go b/internal/api/swagger.go index 1eece87..7f6d6a9 100644 --- a/internal/api/swagger.go +++ b/internal/api/swagger.go @@ -1,15 +1,15 @@ package api -// @title CIC Custodial API -// @version 1.0 -// @description Interact with CIC Custodial API -// @termsOfService https://grassecon.org/pages/terms-and-conditions.html +// @title CIC Custodial API +// @version 1.0 +// @description Interact with CIC Custodial API +// @termsOfService https://grassecon.org/pages/terms-and-conditions.html -// @contact.name API Support -// @contact.url https://grassecon.org/pages/contact-us -// @contact.email devops@grassecon.org +// @contact.name API Support +// @contact.url https://grassecon.org/pages/contact-us +// @contact.email devops@grassecon.org -// @license.name AGPL-3.0 -// @license.url https://www.gnu.org/licenses/agpl-3.0.en.html +// @license.name AGPL-3.0 +// @license.url https://www.gnu.org/licenses/agpl-3.0.en.html -// @BasePath /api +// @BasePath /api diff --git a/internal/api/track.go b/internal/api/track.go index 1463517..6390600 100644 --- a/internal/api/track.go +++ b/internal/api/track.go @@ -7,11 +7,17 @@ import ( "github.com/labstack/echo/v4" ) -// HandleTxStatus route. -// GET: /api/track/:trackingId -// Route param: -// trackingId -> tracking UUID -// Returns array of tx status. +// HandleTrackTx godoc +// @Summary Track an OTX (Origin transaction) status. +// @Description Track an OTX (Origin transaction) status. +// @Tags track +// @Accept */* +// @Produce json +// @Param trackingId path string true "Tracking Id" +// @Success 200 {object} OkResp +// @Failure 400 {object} ErrResp +// @Failure 500 {object} ErrResp +// @Router /track/{trackingId} [get] func HandleTrackTx(cu *custodial.Custodial) func(echo.Context) error { return func(c echo.Context) error { var (