grassrootseconomics/cic-custodial
5
0
Fork 0
mirror of https://github.com/grassrootseconomics/cic-custodial.git synced 2024-12-22 01:47:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: add godocs comments to all routes

Browse Source 
* 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/* ${BUILD_CONF} go build -ldflags="-X main.build=${BUILD_COMMIT} -s -w" -o ${BIN} cmd/service/*
docs: docs:
swag fmt --dir internal/api/
swag init --dir internal/api/ -g swagger.go swag init --dir internal/api/ -g swagger.go
run: run:

2
config.toml
View File

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

190
docs/docs.go
View File

@ -25,7 +25,7 @@ const docTemplate = `{
"host": "{{.Host}}", "host": "{{.Host}}",
"basePath": "{{.BasePath}}", "basePath": "{{.BasePath}}",
"paths": { "paths": {
"/": { "/account/create": {
"post": { "post": {
"description": "Create a new custodial account.", "description": "Create a new custodial account.",
"consumes": [ "consumes": [
@ -34,17 +34,201 @@ const docTemplate = `{
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [
"account"
],
"summary": "Create a new custodial account.", "summary": "Create a new custodial account.",
"responses": { "responses": {
"200": { "200": {
"description": "OK", "description": "OK",
"schema": { "schema": {
"type": "object", "$ref": "#/definitions/api.OkResp"
"additionalProperties": true }
},
"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", "basePath": "/api",
"paths": { "paths": {
"/": { "/account/create": {
"post": { "post": {
"description": "Create a new custodial account.", "description": "Create a new custodial account.",
"consumes": [ "consumes": [
@ -26,17 +26,201 @@
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [
"account"
],
"summary": "Create a new custodial account.", "summary": "Create a new custodial account.",
"responses": { "responses": {
"200": { "200": {
"description": "OK", "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": { "schema": {
"type": "object", "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 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: info:
contact: contact:
email: devops@grassecon.org email: devops@grassecon.org
@ -12,7 +30,7 @@ info:
title: CIC Custodial API title: CIC Custodial API
version: "1.0" version: "1.0"
paths: paths:
/: /account/create:
post: post:
consumes: consumes:
- '*/*' - '*/*'
@ -23,7 +41,109 @@ paths:
"200": "200":
description: OK description: OK
schema: schema:
additionalProperties: true $ref: '#/definitions/api.OkResp'
type: object "500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrResp'
summary: Create a new custodial account. 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" swagger: "2.0"

14
internal/api/account.go
View File

@ -13,12 +13,14 @@ import (
) )
// HandleAccountCreate godoc // HandleAccountCreate godoc
// @Summary Create a new custodial account. // @Summary Create a new custodial account.
// @Description Create a new custodial account. // @Description Create a new custodial account.
// @Accept */* // @Tags account
// @Produce json // @Accept */*
// @Success 200 {object} map[string]interface{} // @Produce json
// @Router / [post] // @Success 200 {object} OkResp
// @Failure 500 {object} ErrResp
// @Router /account/create [post]
func HandleAccountCreate(cu *custodial.Custodial) func(echo.Context) error { func HandleAccountCreate(cu *custodial.Custodial) func(echo.Context) error {
return func(c echo.Context) error { return func(c echo.Context) error {
generatedKeyPair, err := keypair.Generate() generatedKeyPair, err := keypair.Generate()

11
internal/api/network.go
View File

@ -12,6 +12,17 @@ import (
"github.com/labstack/echo/v4" "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 { func HandleNetworkAccountStatus(cu *custodial.Custodial) func(echo.Context) error {
return func(c echo.Context) error { return func(c echo.Context) error {
var ( var (

20
internal/api/sign.go
View File

@ -12,15 +12,17 @@ import (
"github.com/labstack/echo/v4" "github.com/labstack/echo/v4"
) )
// HandleSignTransfer route. // HandleSignTransfer godoc
// POST: /api/sign/transfer // @Summary Sign and dispatch transfer request.
// JSON Body: // @Description Sign and dispatch a transfer request.
// from -> ETH address // @Tags network
// to -> ETH address // @Accept json
// voucherAddress -> ETH address // @Produce json
// amount -> int (6 d.p. precision) // @Param signTransferRequest body object{from=string,to=string,voucherAddress=string,amount=uint64} true "Sign Transfer Request"
// e.g. 1000000 = 1 VOUCHER // @Success 200 {object} OkResp
// Returns the task id. // @Failure 400 {object} ErrResp
// @Failure 500 {object} ErrResp
// @Router /sign/transfer [post]
func HandleSignTransfer(cu *custodial.Custodial) func(echo.Context) error { func HandleSignTransfer(cu *custodial.Custodial) func(echo.Context) error {
return func(c echo.Context) error { return func(c echo.Context) error {
var ( var (

20
internal/api/swagger.go
View File

@ -1,15 +1,15 @@
package api package api
// @title CIC Custodial API // @title CIC Custodial API
// @version 1.0 // @version 1.0
// @description Interact with CIC Custodial API // @description Interact with CIC Custodial API
// @termsOfService https://grassecon.org/pages/terms-and-conditions.html // @termsOfService https://grassecon.org/pages/terms-and-conditions.html
// @contact.name API Support // @contact.name API Support
// @contact.url https://grassecon.org/pages/contact-us // @contact.url https://grassecon.org/pages/contact-us
// @contact.email devops@grassecon.org // @contact.email devops@grassecon.org
// @license.name AGPL-3.0 // @license.name AGPL-3.0
// @license.url https://www.gnu.org/licenses/agpl-3.0.en.html // @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" "github.com/labstack/echo/v4"
) )
// HandleTxStatus route. // HandleTrackTx godoc
// GET: /api/track/:trackingId // @Summary Track an OTX (Origin transaction) status.
// Route param: // @Description Track an OTX (Origin transaction) status.
// trackingId -> tracking UUID // @Tags track
// Returns array of tx status. // @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 { func HandleTrackTx(cu *custodial.Custodial) func(echo.Context) error {
return func(c echo.Context) error { return func(c echo.Context) error {
var ( var (