feat(repo,docs-site): migrate swagger apis to docs

Author: dionysuzx

.github/workflows/blobstorage-preview.yml

@@ -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,38 @@ export default defineConfig({
   },
   integrations: [
     starlight({
-      plugins: [starlightLinksValidator()],
+      plugins: [
+        starlightLinksValidator({
+          exclude: [
+            // "/api-reference/blob-storage",
+            "/api-reference/bridge-relayer",
+            "/api-reference/event-indexer",
+            "/api-reference/prover-server",
+          ],
+        }),
+        starlightOpenAPI([
+          // {
+          //   base: "api-reference/blob-storage",
+          //   label: "Blob Storage API",
+          //   schema: "../blobstorage/docs/swagger.yaml",
+          // },
+          {
+            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 +147,14 @@ export default defineConfig({
             },
           ],
         },
-        {
-          label: "API Reference",
-          autogenerate: { directory: "api-reference" },
-        },
         {
           label: "Resources",
           autogenerate: { directory: "resources" },
         },
+        {
+          label: "API Reference",
+          items: openAPISidebarGroups,
+        },
       ],
     }),
   ],

.github/workflows/blobstorage-production.yml

@@ -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"
   }
 }

packages/docs-site/astro.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(),
       }),
     }),
   }),

packages/docs-site/package.json

@@ -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.