Merge pull request #69 from numary/GoDoc

flemzord · web-flow · commit bde5d670dff7 · 2021-11-25T10:53:00.000+01:00
Add Swagger generator &amp;&amp; Add Logger in JSON
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -5,6 +5,19 @@ on:
 
 name: Main
 jobs:
+  docs:
+    name: 'Build Docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          wget https://github.com/swaggo/swag/releases/download/v1.7.4/swag_1.7.4_Linux_x86_64.tar.gz
+          tar -zxvf swag_1.7.4_Linux_x86_64.tar.gz
+      - run: ./swag init
+      - uses: actions/upload-artifact@v2
+        with:
+          name: docs-dist
+          path: ./docs/**
   build_control:
     name: 'Build Control'
     runs-on: ubuntu-latest
@@ -57,6 +70,11 @@ jobs:
         with:
           name: control-dist
           path: cmd/control/
+      - name: fetch docs
+        uses: actions/download-artifact@v2
+        with:
+          name: docs-dist
+          path: docs/
       - name: OSXCross for CGO Support
         if: matrix.os == 'ubuntu-latest'
         run: |
diff --git a/.github/workflows/pr_open.yml b/.github/workflows/pr_open.yml
@@ -3,6 +3,19 @@ on:
   pull_request:
     types: [assigned, opened, synchronize, reopened]
 jobs:
+  docs:
+    name: 'Build Docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          wget https://github.com/swaggo/swag/releases/download/v1.7.4/swag_1.7.4_Linux_x86_64.tar.gz
+          tar -zxvf swag_1.7.4_Linux_x86_64.tar.gz
+      - run: ./swag init
+      - uses: actions/upload-artifact@v2
+        with:
+          name: docs-dist
+          path: ./docs/**
   build_control:
     name: 'Build Control'
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -5,15 +5,34 @@ on:
 permissions:
   contents: write
 jobs:
+  docs:
+    name: 'Build Docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          wget https://github.com/swaggo/swag/releases/download/v1.7.4/swag_1.7.4_Linux_x86_64.tar.gz
+          tar -zxvf swag_1.7.4_Linux_x86_64.tar.gz
+      - run: ./swag init
+      - uses: actions/upload-artifact@v2
+        with:
+          name: docs-dist
+          path: ./docs/**
   oas:
     name: 'OAS Readme'
     runs-on: ubuntu-latest
+    needs: docs
     steps:
       - uses: actions/checkout@v2
+      - name: fetch docs
+        uses: actions/download-artifact@v2
+        with:
+          name: docs-dist
+          path: docs/
       - uses: readmeio/github-readme-sync@v2
         with:
           readme-oas-key: ${{ secrets.README_OAS_KEY }}
-          oas-file-path: './spec/http.yml'
+          oas-file-path: './docs/swagger.json'
           api-version: 'v1.0-beta' # TODO : Use Release Version
   build_control:
     name: 'Build Control'
@@ -35,7 +54,9 @@ jobs:
           path: ./**
   build:
     name: 'Build'
-    needs: build_control
+    needs:
+      - build_control
+      - docs
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -63,6 +84,11 @@ jobs:
         with:
           name: control-dist
           path: cmd/control/
+      - name: fetch docs
+        uses: actions/download-artifact@v2
+        with:
+          name: docs-dist
+          path: docs/
       - name: Set up QEMU
         if: matrix.os == 'ubuntu-latest'
         uses: docker/setup-qemu-action@v1
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@ coverage.out
 cmd/control/*
 !cmd/control/gitkeep
 .DS_Store
+docs/swagger.json
+docs/swagger.yaml
diff --git a/Makefile b/Makefile
@@ -3,9 +3,3 @@ test:
 
 bench:
 	go test -test.bench=. -run=^a ./...
-
-fetch-control:
-	cd cmd/control && \
-	curl -OL https://numary-control-releases.s3.eu-west-1.amazonaws.com/numary-control.tar.gz && \
-	tar -zxvf numary-control.tar.gz && \
-	rm numary-control.tar.gz
diff --git a/api/controllers/account_controller.go b/api/controllers/account_controller.go
@@ -19,7 +19,14 @@ func NewAccountController() AccountController {
 	return AccountController{}
 }
 
-// GetAccounts -
+// GetAccounts godoc
+// @Summary List All Accounts
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Accept json
+// @Produce json
+// @Success 200 {object} storage.Store{}
+// @Router /{ledger}/accounts [get]
 func (ctl *AccountController) GetAccounts(c *gin.Context) {
 	l, _ := c.Get("ledger")
 	cursor, err := l.(*ledger.Ledger).FindAccounts(
@@ -40,7 +47,15 @@ func (ctl *AccountController) GetAccounts(c *gin.Context) {
 	)
 }
 
-// GetAccount -
+// GetAccount godoc
+// @Summary List Account by Address
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Param accountId path string true "accountId"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/accounts/{accountId} [get]
 func (ctl *AccountController) GetAccount(c *gin.Context) {
 	l, _ := c.Get("ledger")
 	acc, err := l.(*ledger.Ledger).GetAccount(c.Param("address"))
@@ -59,7 +74,15 @@ func (ctl *AccountController) GetAccount(c *gin.Context) {
 	)
 }
 
-// PostAccountMetadata -
+// PostAccountMetadata godoc
+// @Summary Add metadata to account
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Param accountId path string true "accountId"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/accounts/{accountId}/metadata [post]
 func (ctl *AccountController) PostAccountMetadata(c *gin.Context) {
 	l, _ := c.Get("ledger")
 	var m core.Metadata
diff --git a/api/controllers/config_controller.go b/api/controllers/config_controller.go
@@ -1,10 +1,12 @@
 package controllers
 
 import (
+	"github.com/swaggo/swag"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
 	"github.com/numary/ledger/config"
+	_ "github.com/numary/ledger/docs"
 	"github.com/spf13/viper"
 )
 
@@ -18,7 +20,13 @@ func NewConfigController() ConfigController {
 	return ConfigController{}
 }
 
-// GetInfo -
+// GetInfo godoc
+// @Summary Server Info
+// @Schemes
+// @Accept json
+// @Produce json
+// @Success 200 {object} config.ConfigInfo{}
+// @Router /_info [get]
 func (ctl *ConfigController) GetInfo(c *gin.Context) {
 	ctl.response(
 		c,
@@ -35,3 +43,12 @@ func (ctl *ConfigController) GetInfo(c *gin.Context) {
 		},
 	)
 }
+
+func (ctl *ConfigController) GetDocs(c *gin.Context) {
+	doc, err := swag.ReadDoc("swagger")
+	if err != nil {
+		c.AbortWithStatus(http.StatusInternalServerError)
+		return
+	}
+	c.Writer.Write([]byte(doc))
+}
diff --git a/api/controllers/ledger_controller.go b/api/controllers/ledger_controller.go
@@ -17,7 +17,15 @@ func NewLedgerController() LedgerController {
 	return LedgerController{}
 }
 
-// GetStats -
+// GetStats godoc
+// @Summary Get ledger stats (aggregate metrics on accounts and transactions)
+// @Schemes
+// @Description The stats for account
+// @Accept json
+// @Produce json
+// @Param ledger path string true "ledger"
+// @Success 200 {object} ledger.Stats{}
+// @Router /{ledger}/stats [get]
 func (ctl *LedgerController) GetStats(c *gin.Context) {
 	l, _ := c.Get("ledger")
 
diff --git a/api/controllers/script_controller.go b/api/controllers/script_controller.go
@@ -22,7 +22,14 @@ func NewScriptController() ScriptController {
 	return ScriptController{}
 }
 
-// PostScript -
+// PostScript godoc
+// @Summary Execute a Numscript and commit transaction if any
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/script [post]
 func (ctl *ScriptController) PostScript(c *gin.Context) {
 	l, _ := c.Get("ledger")
 
diff --git a/api/controllers/transaction_controller.go b/api/controllers/transaction_controller.go
@@ -19,7 +19,15 @@ func NewTransactionController() TransactionController {
 	return TransactionController{}
 }
 
-// GetTransactions -
+// GetTransactions godoc
+// @Summary Get Transactions
+// @Schemes
+// @Description List transactions
+// @Param ledger path string true "ledger"
+// @Accept json
+// @Produce json
+// @Success 200 {object} storage.Store{}
+// @Router /{ledger}/transactions [get]
 func (ctl *TransactionController) GetTransactions(c *gin.Context) {
 	l, _ := c.Get("ledger")
 	cursor, err := l.(*ledger.Ledger).FindTransactions(
@@ -42,7 +50,15 @@ func (ctl *TransactionController) GetTransactions(c *gin.Context) {
 	)
 }
 
-// PostTransaction -
+// PostTransactions godoc
+// @Summary Commit a new transaction to the ledger
+// @Schemes
+// @Description Commit a new transaction to the ledger
+// @Param ledger path string true "ledger"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/transactions [post]
 func (ctl *TransactionController) PostTransaction(c *gin.Context) {
 	l, _ := c.Get("ledger")
 
@@ -65,7 +81,15 @@ func (ctl *TransactionController) PostTransaction(c *gin.Context) {
 	)
 }
 
-// RevertTransaction -
+// RevertTransaction godoc
+// @Summary Revert transaction
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Param reference path string true "reference"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/transactions/{reference}/revert [post]
 func (ctl *TransactionController) RevertTransaction(c *gin.Context) {
 	l, _ := c.Get("ledger")
 	err := l.(*ledger.Ledger).RevertTransaction(c.Param("transactionId"))
@@ -84,7 +108,15 @@ func (ctl *TransactionController) RevertTransaction(c *gin.Context) {
 	)
 }
 
-// PostTransactionMetadata -
+// PostTransactionMetadata godoc
+// @Summary Set metadata on transaction
+// @Schemes
+// @Param ledger path string true "ledger"
+// @Param reference path string true "reference"
+// @Accept json
+// @Produce json
+// @Success 200 {string} string	""
+// @Router /{ledger}/transactions/{reference}/metadata [post]
 func (ctl *TransactionController) PostTransactionMetadata(c *gin.Context) {
 	l, _ := c.Get("ledger")
 
diff --git a/api/routes/routes.go b/api/routes/routes.go
@@ -2,6 +2,7 @@ package routes
 
 import (
 	"github.com/gin-contrib/cors"
+	"github.com/gin-contrib/logger"
 	"github.com/gin-gonic/gin"
 	"github.com/numary/ledger/api/controllers"
 	"github.com/numary/ledger/api/middlewares"
@@ -50,15 +51,18 @@ func NewRoutes(
 
 // Engine -
 func (r *Routes) Engine(cc cors.Config) *gin.Engine {
-	engine := gin.Default()
+	engine := gin.New()
 
 	// Default Middlewares
 	engine.Use(
 		cors.New(cc),
 		gin.Recovery(),
+		logger.SetLogger(),
 		r.authMiddleware.AuthMiddleware(engine),
 	)
 
+	engine.GET("/swagger.json", r.configController.GetDocs)
+
 	// API Routes
 	engine.GET("/_info", r.configController.GetInfo)
 
diff --git a/docs/docs.go b/docs/docs.go
diff --git a/go.mod b/go.mod
diff --git a/go.sum b/go.sum
diff --git a/main.go b/main.go
diff --git a/spec/http.yml b/spec/http.yml
