Merge pull request #1432 from 0chain/doc/update

Doc/update

Author: dabasov

Makefile

@@ -188,3 +188,10 @@ else
 	sed -i "s/BUF_VERSION := [0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*/BUF_VERSION := $(VERSION)/g" Makefile
 endif
 endif
+
+.PHONY: markdown-docs
+markdown-docs:
+	swagger generate spec -o ./swagger.yaml -w ./code/go/0chain.net -m
+	sed -i '' "s/in\:\ form/in\:\ formData/g" ./swagger.yaml
+	yq -i '(.paths.*.*.parameters.[] | select(.in == "formData") | select(.type == "object")).type = "file"' swagger.yaml
+	swagger generate markdown -f ./swagger.yaml --output=swagger.md

code/go/0chain.net/blobbercore/allocation/entity.go

@@ -38,6 +38,7 @@ const (
 	CanRenameMask       = uint16(32) // 0010 0000
 )
 
+// swagger:model Allocation
 type Allocation struct {
 	ID             string           `gorm:"column:id;size:64;primaryKey"`
 	Tx             string           `gorm:"column:tx;size:64;not null;unique;index:idx_unique_allocations_tx,unique"`
@@ -239,6 +240,7 @@ const (
 )
 
 // Terms for allocation by its Tx.
+// swagger:model
 type Terms struct {
 	ID           int64      `gorm:"column:id;primaryKey"`
 	BlobberID    string     `gorm:"blobber_id;size:64;not null"`

code/go/0chain.net/blobbercore/allocation/file_changer_base.go

@@ -11,6 +11,7 @@ import (
 	"github.com/0chain/blobber/code/go/0chain.net/core/encryption"
 )
 
+// swagger:model BaseFileChanger 
 // BaseFileChanger base file change processor
 type BaseFileChanger struct {
 	//client side: unmarshal them from 'updateMeta'/'uploadMeta'

code/go/0chain.net/blobbercore/allocation/file_changer_upload.go

@@ -16,6 +16,7 @@ import (
 	"github.com/0chain/blobber/code/go/0chain.net/core/common"
 )
 
+// swagger:model UploadFileChanger
 // UploadFileChanger file change processor for continuous upload in INIT/APPEND/FINALIZE
 type UploadFileChanger struct {
 	BaseFileChanger

code/go/0chain.net/blobbercore/blobberhttp/response.go

@@ -55,6 +55,7 @@ type ListResult struct {
 	Entities       []map[string]interface{} `json:"list"`
 }
 
+// swagger:model DownloadResponse
 type DownloadResponse struct {
 	Success      bool                   `json:"success"`
 	Data         []byte                 `json:"data"`
@@ -63,6 +64,7 @@ type DownloadResponse struct {
 	LatestRM     *readmarker.ReadMarker `json:"latest_rm"`
 }
 
+// swagger:model LatestWriteMarkerResult
 type LatestWriteMarkerResult struct {
 	LatestWM *writemarker.WriteMarker `json:"latest_write_marker"`
 	PrevWM   *writemarker.WriteMarker `json:"prev_write_marker"`

code/go/0chain.net/blobbercore/challenge/timing.go

@@ -12,6 +12,7 @@ import (
 	"gorm.io/gorm/clause"
 )
 
+// swagger:model ChallengeTiming
 type ChallengeTiming struct {
 	// ChallengeID is the challenge ID generated on blockchain.
 	ChallengeID string `gorm:"column:challenge_id;size:64;primaryKey" json:"id"`

code/go/0chain.net/blobbercore/filestore/store.go

@@ -90,6 +90,7 @@ func GetFileStore() FileStorer {
 	return fileStore
 }
 
+// swagger:model FileDownloadResponse
 type FileDownloadResponse struct {
 	Nodes   [][][]byte
 	Indexes [][]int

code/go/0chain.net/blobbercore/handler/auth_ticket.go

@@ -7,6 +7,29 @@ import (
 	"net/http"
 )
 
+// swagger:model AuthTicketResponse
+type AuthTicketResponse struct {
+	AuthTicket string `json:"auth_ticket"`
+}
+
+// swagger:route GET /v1/auth/generate GetAuthTicket
+// Generate blobber authentication ticket.
+//
+// Generate and retrieve blobber authentication ticket signed by the blobber's signature. Used by restricted blobbers to enable users to use them to host allocations.
+//
+// parameters:
+//
+//   +name: Zbox-Signature
+//    in: header
+//    type: string
+//    description: Digital signature to verify that the sender is 0box service.
+//   +name: client_id
+//    type: string
+//    in: query
+//    description: Client ID is used as a payload to the token generated. The token represents a signed version of this string by the blobber's private key.
+//
+// responses:
+//    200: AuthTicketResponse
 func GenerateAuthTicket(ctx context.Context, r *http.Request) (interface{}, error) {
 	clientID := r.URL.Query().Get("client_id")
 	if clientID == "" {
@@ -18,7 +41,7 @@ func GenerateAuthTicket(ctx context.Context, r *http.Request) (interface{}, erro
 		return nil, common.NewError("signature_failed", "signature failed")
 	}
 
-	return map[string]interface{}{
-		"auth_ticket": signature,
+	return &AuthTicketResponse{
+		AuthTicket: signature,
 	}, nil
 }

code/go/0chain.net/blobbercore/handler/challenge_timings.go

@@ -8,6 +8,41 @@ import (
 	"strconv"
 )
 
+// swagger:route GET /challengetimings GetChallengeTimings
+// Get challenge timings.
+//
+// Retrieve challenge timings for the blobber admin.
+//
+// parameters:
+//
+//   +name: Authorization
+//     in: header
+//     type: string
+//     required: true
+//     description: Authorization header (Basic auth). MUST be provided to fulfil the request
+//   +name: from
+//     in: query
+//     type: integer
+//     required: false
+//     description: An optional timestamp from which to retrieve the challenge timings
+//   +name: offset
+//     in: query
+//     type: integer
+//     required: false
+//     description: Pagination offset, start of the page to retrieve. Default is 0.
+//   +name: limit
+//     in: query
+//     type: integer
+//     required: false
+//     description: Pagination limit, number of entries in the page to retrieve. Default is 20.
+//   +name: sort
+//     in: query
+//     type: string
+//     required: false
+//     description: Direction of sorting based on challenge closure time, either "asc" or "desc". Default is "asc"
+//
+// responses:
+//   200: []ChallengeTiming
 func GetChallengeTimings(ctx context.Context, r *http.Request) (interface{}, error) {
 	var (
 		fromString = r.URL.Query().Get("from")
@@ -30,6 +65,25 @@ func GetChallengeTimings(ctx context.Context, r *http.Request) (interface{}, err
 	return challenge.GetChallengeTimings(from, limit)
 }
 
+// swagger:route GET /challenge-timings-by-challengeId GetChallengeTimingByChallengeID
+// Get challenge timing by challenge ID.
+// Retrieve challenge timing for the given challenge ID by the blobber admin.
+//
+// parameters:
+//
+//   +name: Authorization
+//     in: header
+//     type: string
+//     required: true
+//     description: Authorization header (Basic auth). MUST be provided to fulfil the request
+//   +name: challenge_id
+//     in: query
+//     type: string
+//     required: true
+//     description: Challenge ID for which to retrieve the challenge timing
+//
+// responses:
+//   200: ChallengeTiming
 func GetChallengeTiming(ctx context.Context, r *http.Request) (interface{}, error) {
 	var (
 		challengeID = r.URL.Query().Get("challenge_id")