docs(blobstorage): add swagger docs for blobstorage (#16487)

taikoxyz · Mar 20, 2024 · 7b62ac1 · 7b62ac1
1 parent 72d74b1
commit 7b62ac1
Show file tree

Hide file tree

Showing 7 changed files with 269 additions and 12 deletions.
diff --git a/packages/blobstorage/docs/docs.go b/packages/blobstorage/docs/docs.go
@@ -0,0 +1,98 @@
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "termsOfService": "http://swagger.io/terms/",
+        "contact": {
+            "name": "API Support",
+            "url": "https://community.taiko.xyz/",
+            "email": "[email protected]"
+        },
+        "license": {
+            "name": "MIT"
+        },
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/getBlob": {
+            "get": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "Get blob(s) and KZG commitment(s)",
+                "operationId": "get-blob",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "blobHash to query",
+                        "name": "blobHash",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/http.getBlobResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "http.blobData": {
+            "type": "object",
+            "properties": {
+                "blob_hash": {
+                    "type": "string"
+                },
+                "kzg_commitment": {
+                    "type": "string"
+                }
+            }
+        },
+        "http.getBlobResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/http.blobData"
+                    }
+                }
+            }
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "blobs.internal.taiko.xyz",
+	BasePath:         "",
+	Schemes:          []string{},
+	Title:            "Taiko Blobstorage API",
+	Description:      "",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}
diff --git a/packages/blobstorage/docs/index.html b/packages/blobstorage/docs/index.html
@@ -0,0 +1,29 @@
+<html>
+    <head>
+        <!-- Load the latest Swagger UI code and style from npm using unpkg.com -->
+        <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+        <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css"/>
+        <title>Blobstorage API</title>
+    </head>
+    <body>
+        <div id="swagger-ui"></div> <!-- Div to hold the UI component -->
+        <script>
+            window.onload = function () {
+                // Begin Swagger UI call region
+                const ui = SwaggerUIBundle({
+                    url: "/swagger.json", //Location of Open API spec in the repo
+                    dom_id: '#swagger-ui',
+                    deepLinking: true,
+                    presets: [
+                        SwaggerUIBundle.presets.apis,
+                        SwaggerUIBundle.SwaggerUIStandalonePreset
+                    ],
+                    plugins: [
+                        SwaggerUIBundle.plugins.DownloadUrl
+                    ],
+                })
+                window.ui = ui
+            }
+        </script>
+    </body>
+</html>
diff --git a/packages/blobstorage/docs/swagger.json b/packages/blobstorage/docs/swagger.json
@@ -0,0 +1,68 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "Taiko Blobstorage API",
+    "termsOfService": "http://swagger.io/terms/",
+    "contact": {
+      "name": "API Support",
+      "url": "https://community.taiko.xyz/",
+      "email": "[email protected]"
+    },
+    "license": {
+      "name": "MIT"
+    },
+    "version": "1.0"
+  },
+  "host": "blobs.internal.taiko.xyz",
+  "paths": {
+    "/getBlob": {
+      "get": {
+        "consumes": ["application/json"],
+        "produces": ["application/json"],
+        "summary": "Get blob(s) and KZG commitment(s)",
+        "operationId": "get-blob",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "blobHash to query",
+            "name": "blobHash",
+            "in": "query",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/http.getBlobResponse"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "http.blobData": {
+      "type": "object",
+      "properties": {
+        "blob_hash": {
+          "type": "string"
+        },
+        "kzg_commitment": {
+          "type": "string"
+        }
+      }
+    },
+    "http.getBlobResponse": {
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/http.blobData"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/packages/blobstorage/docs/swagger.yaml b/packages/blobstorage/docs/swagger.yaml
@@ -0,0 +1,47 @@
+definitions:
+  http.blobData:
+    properties:
+      blob_hash:
+        type: string
+      kzg_commitment:
+        type: string
+    type: object
+  http.getBlobResponse:
+    properties:
+      data:
+        items:
+          $ref: "#/definitions/http.blobData"
+        type: array
+    type: object
+host: blobs.internal.taiko.xyz
+info:
+  contact:
+    email: [email protected]
+    name: API Support
+    url: https://community.taiko.xyz/
+  license:
+    name: MIT
+  termsOfService: http://swagger.io/terms/
+  title: Taiko Blobstorage API
+  version: "1.0"
+paths:
+  /getBlob:
+    get:
+      consumes:
+        - application/json
+      operationId: get-blob
+      parameters:
+        - description: blobHash to query
+          in: query
+          name: blobHash
+          required: true
+          type: string
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: "#/definitions/http.getBlobResponse"
+      summary: Get blob(s) and KZG commitment(s)
+swagger: "2.0"
diff --git a/packages/blobstorage/pkg/http/get_blob.go b/packages/blobstorage/pkg/http/get_blob.go
@@ -10,7 +10,7 @@ import (
 	"gorm.io/gorm"
 )
 
-type resp struct {
+type getBlobResponse struct {
 	Data []blobData `bson:"data" json:"data"`
 }
 
@@ -19,6 +19,17 @@ type blobData struct {
 	KzgCommitment string `bson:"kzg_commitment" json:"kzg_commitment"`
 }
 
+// GetBlob
+//
+//	 returns blob and kzg commitment by blobHash or multiple comma-separated blobHashes
+//
+//	@Summary	Get blob(s) and KZG commitment(s)
+//	@ID			get-blob
+//	@Param		blobHash	query	string	true "blobHash to query"
+//	@Accept		json
+//	@Produce	json
+//	@Success	200	{object}	getBlobResponse
+//	@Router		/getBlob [get]
 func (srv *Server) GetBlob(c echo.Context) error {
 	blobHashes := c.QueryParam("blobHash")
 	if blobHashes == "" {
@@ -30,7 +41,7 @@ func (srv *Server) GetBlob(c echo.Context) error {
 		return webutils.LogAndRenderErrors(c, http.StatusBadRequest, err)
 	}
 
-	response := resp{
+	response := getBlobResponse{
 		Data: make([]blobData, 0),
 	}
 
@@ -46,7 +57,7 @@ func (srv *Server) GetBlob(c echo.Context) error {
 	return c.JSON(http.StatusOK, response)
 }
 
-// getBlobData retrieves blob data from MongoDB based on blobHashes.
+// getBlobData retrieves blob data from MySQL based on blobHashes.
 func (srv *Server) getBlobData(blobHashes []string) ([]blobData, error) {
 	var results []blobData
 

diff --git a/packages/blobstorage/pkg/http/server.go b/packages/blobstorage/pkg/http/server.go
@@ -17,18 +17,19 @@ type ethClient interface {
 	ChainID(ctx context.Context) (*big.Int, error)
 }
 
-// @title Taiko Relayer API
-// @version 1.0
-// @termsOfService http://swagger.io/terms/
+//	@title			Taiko Blobstorage API
+//	@version		1.0
+//	@termsOfService	http://swagger.io/terms/
 
-// @contact.name API Support
-// @contact.url https://community.taiko.xyz/
-// @contact.email [email protected]
+//	@contact.name	API Support
+//	@contact.url	https://community.taiko.xyz/
+//	@contact.email	[email protected]
 
-// @license.name MIT
+//	@license.name	MIT
 
-// @host relayer.katla.taiko.xyz
-// Server represents an relayer http server instance.
+//	@host	blobs.internal.taiko.xyz
+//
+// Server represents an blobstorage http server instance.
 type Server struct {
 	echo         *echo.Echo
 	blobHashRepo blobstorage.BlobHashRepository

diff --git a/packages/blobstorage/scripts/swagger.sh b/packages/blobstorage/scripts/swagger.sh
@@ -0,0 +1,3 @@
+#/bin/sh
+
+swag init -g server.go -d pkg/http --parseDependency