grassrootseconomics
/
cic-custodial
mirror of https://github.com/grassrootseconomics/cic-custodial.git
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add godocs comments to all routes 

* disable serving docs by default
This commit is contained in:
Mohamed Sohail 2023-04-14 07:56:21 +00:00
parent 223656b2bc
commit e91f82c08a
Signed by: kamikazechaser
GPG Key ID: 7DD45520C01CD85D
10 changed files with 549 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

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

2
config.toml
View File

@ -3,7 +3,7 @@ address = ":5000"
# Exposes Go process Prometheus metrics
# /metrics endpoint
metrics = true
docs = true
docs = false
[chain]
rpc_endpoint = ""

190
docs/docs.go
View File

@ -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"
}
}
}
}
}`

188
docs/swagger.json
View File

@ -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"
}
}
}
}
}

126
docs/swagger.yaml
View File

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

14
internal/api/account.go
View File

@ -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()

11
internal/api/network.go
View File

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

20
internal/api/sign.go
View File

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

20
internal/api/swagger.go
View File

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

16
internal/api/track.go
View File

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