feat(docs-site): add all swagger apis

taikoxyz · May 13, 2024 · b97d2a4 · b97d2a4
1 parent 24168e4
commit b97d2a4
Show file tree

Hide file tree

Showing 16 changed files with 1,881 additions and 1,652 deletions.
diff --git a/packages/docs-site/astro.config.ts b/packages/docs-site/astro.config.ts
@@ -1,6 +1,7 @@
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import starlightLinksValidator from "starlight-links-validator";
+import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi";
 
 // https://astro.build/config
 export default defineConfig({
@@ -13,7 +14,26 @@ export default defineConfig({
   },
   integrations: [
     starlight({
-      plugins: [starlightLinksValidator()],
+      plugins: [
+        starlightLinksValidator(),
+        starlightOpenAPI([
+          {
+            base: "api-reference/bridge-relayer",
+            label: "Bridge Relayer API",
+            schema: "../relayer/docs/swagger.yaml",
+          },
+          {
+            base: "api-reference/event-indexer",
+            label: "Event Indexer API",
+            schema: "../eventindexer/docs/swagger.yaml",
+          },
+          {
+            base: "api-reference/prover-server",
+            label: "Prover Server API",
+            schema: "../taiko-client/docs/swagger.yaml",
+          },
+        ]),
+      ],
       components: {
         SiteTitle: "./src/components/starlight/SiteTitle.astro",
         Head: "./src/components/starlight/Head.astro",
@@ -115,14 +135,14 @@ export default defineConfig({
             },
           ],
         },
-        {
-          label: "API Reference",
-          autogenerate: { directory: "api-reference" },
-        },
         {
           label: "Resources",
           autogenerate: { directory: "resources" },
         },
+        {
+          label: "API Reference",
+          items: openAPISidebarGroups,
+        },
       ],
     }),
   ],

diff --git a/packages/docs-site/package.json b/packages/docs-site/package.json
@@ -12,11 +12,12 @@
   "dependencies": {
     "@astrojs/check": "^0.6.0",
     "@astrojs/starlight": "^0.22.2",
-    "astro": "^4.7.1",
-    "astro-og-canvas": "^0.4.2",
+    "astro": "^4.8.3",
+    "astro-og-canvas": "^0.5.0",
     "canvaskit-wasm": "^0.39.1",
     "sharp": "^0.33.3",
-    "starlight-links-validator": "^0.6.0",
-    "typescript": "^5.4.3"
+    "starlight-links-validator": "^0.8.0",
+    "starlight-openapi": "^0.6.3",
+    "typescript": "^5.4.5"
   }
 }
diff --git a/packages/docs-site/src/content/config.ts b/packages/docs-site/src/content/config.ts
@@ -7,7 +7,7 @@ export const collections = {
       extend: z.object({
         description: z
           .string()
-          .max(160, { message: "Must be 160 characters or less." }),
+          .max(160, { message: "Must be 160 characters or less." }).optional(),
       }),
     }),
   }),

diff --git a/packages/docs-site/src/content/docs/api-reference/bridge-relayer-api.md b/packages/docs-site/src/content/docs/api-reference/bridge-relayer-api.md
diff --git a/packages/docs-site/src/content/docs/api-reference/event-indexer-api.md b/packages/docs-site/src/content/docs/api-reference/event-indexer-api.md
diff --git a/packages/docs-site/src/content/docs/api-reference/prover-server-api.md b/packages/docs-site/src/content/docs/api-reference/prover-server-api.md
diff --git a/packages/docs-site/src/content/docs/api-reference/taiko-node-api.md b/packages/docs-site/src/content/docs/api-reference/taiko-node-api.md
diff --git a/packages/docs-site/src/content/docs/core-concepts/taiko-nodes.md b/packages/docs-site/src/content/docs/core-concepts/taiko-nodes.md
@@ -85,3 +85,23 @@ If the proposed block has a **valid** or **invalid** `txList`, the `prover`:
 
 1. Generates a Merkle proof of the block's `TaikoL2.anchor` transaction to prove its existence in the `block.txRoot`'s [MPT](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/) and this transaction receipt's [Merkle proof](https://rollup-glossary.vercel.app/other-terms#merkle-proofs) in the `block.receiptRoot`'s MPT from the L2 execution engine.
 2. Submits the `TaikoL2.anchor` transaction's RLP encoded bytes, its receipt's RLP encoded bytes, the generated Merkle proofs, and a validity proof to prove this block **valid** by sending a `TaikoL1.proveBlock` transaction (the block is valid even for an invalid `txList` because we prove the invalid `txList` maps to an empty block with only the anchor transaction).
+
+## Taiko Node API
+
+Using a Taiko node should feel the same as using any other L1 node, because we essentially re-use the L1 client and make a few backwards-compatible modifications. You can first read about the architecture of Taiko nodes [here](/core-concepts/taiko-nodes).
+
+### Differences from a Geth client
+
+View the fork diff page to see the minimal set of changes made to Geth [here](https://geth.taiko.xyz).
+
+### Execution JSON-RPC API
+
+Check out the execution client spec [here](https://ethereum.github.io/execution-apis/api-documentation/).
+
+### Engine API
+
+Check out the engine API spec [here](https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md).
+
+### Hive test harness
+
+If a Taiko node should feel the same as using any other L1 node, it should surely be able to pass the [hive e2e test harness](https://github.com/ethereum/hive). At the time of writing, the hive tests are actually one of the best references for what the API of an Ethereum node actually is.
diff --git a/packages/docs-site/src/pages/og/[...slug].ts b/packages/docs-site/src/pages/og/[...slug].ts
@@ -11,13 +11,10 @@ export const { getStaticPaths, GET } = OGImageRoute({
   getImageOptions: (_path, page: (typeof pages)[number]) => {
     return {
       title: page.data.title,
-      description: page.data.description,
+      description: page.data.description ?? "",
       logo: {
         path: "./src/assets/taiko-og-logo.png",
       },
-      // bgImage: {
-      //   path: "./src/assets/taiko-og-bg.png",
-      // },
       bgGradient: [
         [15, 2, 15],
         [58, 12, 36],

diff --git a/packages/eventindexer/docs/docs.go b/packages/eventindexer/docs/docs.go
@@ -1,4 +1,4 @@
-// Code generated by swaggo/swag. DO NOT EDIT
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
 package docs
 
 import "github.com/swaggo/swag"
@@ -167,26 +167,6 @@ const docTemplate = `{
                 }
             }
         },
-        "/stats": {
-            "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
-                "summary": "Get stats",
-                "operationId": "get-stats",
-                "responses": {
-                    "200": {
-                        "description": "OK",
-                        "schema": {
-                            "$ref": "#/definitions/eventindexer.Stat"
-                        }
-                    }
-                }
-            }
-        },
         "/uniqueProposers": {
             "get": {
                 "consumes": [
@@ -251,32 +231,6 @@ const docTemplate = `{
                 }
             }
         },
-        "eventindexer.Stat": {
-            "type": "object",
-            "properties": {
-                "averageProofReward": {
-                    "type": "string"
-                },
-                "averageProofTime": {
-                    "type": "string"
-                },
-                "feeTokenAddress": {
-                    "type": "string"
-                },
-                "id": {
-                    "type": "integer"
-                },
-                "numBlocksAssigned": {
-                    "type": "integer"
-                },
-                "numProofs": {
-                    "type": "integer"
-                },
-                "statType": {
-                    "type": "string"
-                }
-            }
-        },
         "eventindexer.UniqueProposersResponse": {
             "type": "object",
             "properties": {
@@ -376,6 +330,8 @@ var SwaggerInfo = &swag.Spec{
 	Description:      "",
 	InfoInstanceName: "swagger",
 	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
 }
 
 func init() {

diff --git a/packages/eventindexer/docs/swagger.json b/packages/eventindexer/docs/swagger.json
@@ -143,22 +143,6 @@
         }
       }
     },
-    "/stats": {
-      "get": {
-        "consumes": ["application/json"],
-        "produces": ["application/json"],
-        "summary": "Get stats",
-        "operationId": "get-stats",
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "$ref": "#/definitions/eventindexer.Stat"
-            }
-          }
-        }
-      }
-    },
     "/uniqueProposers": {
       "get": {
         "consumes": ["application/json"],
@@ -215,32 +199,6 @@
         }
       }
     },
-    "eventindexer.Stat": {
-      "type": "object",
-      "properties": {
-        "averageProofReward": {
-          "type": "string"
-        },
-        "averageProofTime": {
-          "type": "string"
-        },
-        "feeTokenAddress": {
-          "type": "string"
-        },
-        "id": {
-          "type": "integer"
-        },
-        "numBlocksAssigned": {
-          "type": "integer"
-        },
-        "numProofs": {
-          "type": "integer"
-        },
-        "statType": {
-          "type": "string"
-        }
-      }
-    },
     "eventindexer.UniqueProposersResponse": {
       "type": "object",
       "properties": {

diff --git a/packages/eventindexer/docs/swagger.yaml b/packages/eventindexer/docs/swagger.yaml
@@ -13,23 +13,6 @@ definitions:
           $ref: "#/definitions/eventindexer.ChartItem"
         type: array
     type: object
-  eventindexer.Stat:
-    properties:
-      averageProofReward:
-        type: string
-      averageProofTime:
-        type: string
-      feeTokenAddress:
-        type: string
-      id:
-        type: integer
-      numBlocksAssigned:
-        type: integer
-      numProofs:
-        type: integer
-      statType:
-        type: string
-    type: object
   eventindexer.UniqueProposersResponse:
     properties:
       address:
@@ -194,19 +177,6 @@ paths:
           schema:
             $ref: "#/definitions/paginate.Page"
       summary: Get nft balances by address and chain ID
-  /stats:
-    get:
-      consumes:
-        - application/json
-      operationId: get-stats
-      produces:
-        - application/json
-      responses:
-        "200":
-          description: OK
-          schema:
-            $ref: "#/definitions/eventindexer.Stat"
-      summary: Get stats
   /uniqueProposers:
     get:
       consumes:

diff --git a/packages/relayer/docs/docs.go b/packages/relayer/docs/docs.go
@@ -126,6 +126,12 @@ const docTemplate = `{
         "paginate.Page": {
             "type": "object",
             "properties": {
+                "error": {
+                    "type": "boolean"
+                },
+                "error_message": {
+                    "type": "string"
+                },
                 "first": {
                     "type": "boolean"
                 },

diff --git a/packages/relayer/docs/swagger.json b/packages/relayer/docs/swagger.json
@@ -110,6 +110,12 @@
     "paginate.Page": {
       "type": "object",
       "properties": {
+        "error": {
+          "type": "boolean"
+        },
+        "error_message": {
+          "type": "string"
+        },
         "first": {
           "type": "boolean"
         },

diff --git a/packages/relayer/docs/swagger.yaml b/packages/relayer/docs/swagger.yaml
@@ -17,6 +17,10 @@ definitions:
     type: object
   paginate.Page:
     properties:
+      error:
+        type: boolean
+      error_message:
+        type: string
       first:
         type: boolean
       items: {}