From ab4e613de050d7e77b7942f02f9d596bf718fc75 Mon Sep 17 00:00:00 2001 From: Roger <50648015+RogerLamTd@users.noreply.github.com> Date: Tue, 17 Oct 2023 23:40:48 -0700 Subject: [PATCH] feat(docs): host swagger doc by github page (#427) Co-authored-by: David --- .github/workflows/swagger.yml | 61 +++++++++++++++++++++++++++++++++++ docs/docs.go | 22 ++++++++----- docs/swagger.json | 21 +++++++----- docs/swagger.yaml | 19 ++++++----- index.html | 29 +++++++++++++++++ prover/server/api.go | 11 +++++++ scripts/gen_swagger_json.sh | 3 ++ 7 files changed, 142 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/swagger.yml create mode 100644 index.html create mode 100755 scripts/gen_swagger_json.sh diff --git a/.github/workflows/swagger.yml b/.github/workflows/swagger.yml new file mode 100644 index 000000000..3f459f915 --- /dev/null +++ b/.github/workflows/swagger.yml @@ -0,0 +1,61 @@ +name: Swagger + +on: + push: + branches: + - main + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + name: Swagger autogen docs + runs-on: ubuntu-latest + + steps: + - name: checkout + uses: actions/checkout@v2 + + - name: Set up Go + uses: actions/setup-go@v3 + with: + go-version: 1.21 + cache: true + + - name: install swag cli + run: go install github.com/swaggo/swag/cmd/swag@latest + + - name: swag init + run: ./scripts/gen_swagger_json.sh + + deploy: + if: ${{ always() }} + needs: build + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + name: github pages deploy swagger docs + runs-on: ubuntu-latest + + steps: + - name: checkout + uses: actions/checkout@v2 + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: '.' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/docs/docs.go b/docs/docs.go index 6b74be4e4..4278f7146 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -17,7 +17,7 @@ const docTemplate = `{ }, "license": { "name": "MIT", - "url": "hhttps://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md" + "url": "https://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md" }, "version": "{{.Version}}" }, @@ -38,7 +38,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/server.ProposeBlockResponse" + "$ref": "#/definitions/prover_server.ProposeBlockResponse" } }, "422": { @@ -64,7 +64,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/server.Status" + "$ref": "#/definitions/prover_server.Status" } } } @@ -72,7 +72,7 @@ const docTemplate = `{ } }, "definitions": { - "server.ProposeBlockResponse": { + "prover_server.ProposeBlockResponse": { "type": "object", "properties": { "prover": { @@ -86,7 +86,7 @@ const docTemplate = `{ } } }, - "server.Status": { + "prover_server.Status": { "type": "object", "properties": { "currentCapacity": { @@ -95,7 +95,13 @@ const docTemplate = `{ "maxExpiry": { "type": "integer" }, - "minProofFee": { + "minOptimisticTierFee": { + "type": "integer" + }, + "minPseZkevmTierFee": { + "type": "integer" + }, + "minSgxTierFee": { "type": "integer" } } @@ -106,10 +112,10 @@ const docTemplate = `{ // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ Version: "1.0", - Host: "prover-api.test.taiko.xyz", + Host: "", BasePath: "", Schemes: []string{}, - Title: "Taiko Prover API", + Title: "Taiko Prover Server API", Description: "", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, diff --git a/docs/swagger.json b/docs/swagger.json index f16625eaa..762125c07 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -1,7 +1,7 @@ { "swagger": "2.0", "info": { - "title": "Taiko Prover API", + "title": "Taiko Prover Server API", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "API Support", @@ -10,11 +10,10 @@ }, "license": { "name": "MIT", - "url": "hhttps://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md" + "url": "https://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md" }, "version": "1.0" }, - "host": "prover-api.test.taiko.xyz", "paths": { "/assignment": { "post": { @@ -30,7 +29,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/server.ProposeBlockResponse" + "$ref": "#/definitions/prover_server.ProposeBlockResponse" } }, "422": { @@ -56,7 +55,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/server.Status" + "$ref": "#/definitions/prover_server.Status" } } } @@ -64,7 +63,7 @@ } }, "definitions": { - "server.ProposeBlockResponse": { + "prover_server.ProposeBlockResponse": { "type": "object", "properties": { "prover": { @@ -78,7 +77,7 @@ } } }, - "server.Status": { + "prover_server.Status": { "type": "object", "properties": { "currentCapacity": { @@ -87,7 +86,13 @@ "maxExpiry": { "type": "integer" }, - "minProofFee": { + "minOptimisticTierFee": { + "type": "integer" + }, + "minPseZkevmTierFee": { + "type": "integer" + }, + "minSgxTierFee": { "type": "integer" } } diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 7646ebaf3..3664a3f93 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1,5 +1,5 @@ definitions: - server.ProposeBlockResponse: + prover_server.ProposeBlockResponse: properties: prover: type: string @@ -8,16 +8,19 @@ definitions: type: integer type: array type: object - server.Status: + prover_server.Status: properties: currentCapacity: type: integer maxExpiry: type: integer - minProofFee: + minOptimisticTierFee: + type: integer + minPseZkevmTierFee: + type: integer + minSgxTierFee: type: integer type: object -host: prover-api.test.taiko.xyz info: contact: email: info@taiko.xyz @@ -25,9 +28,9 @@ info: url: https://community.taiko.xyz/ license: name: MIT - url: hhttps://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md + url: https://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md termsOfService: http://swagger.io/terms/ - title: Taiko Prover API + title: Taiko Prover Server API version: "1.0" paths: /assignment: @@ -41,7 +44,7 @@ paths: "200": description: OK schema: - $ref: '#/definitions/server.ProposeBlockResponse' + $ref: '#/definitions/prover_server.ProposeBlockResponse' "422": description: prover does not have capacity schema: @@ -58,6 +61,6 @@ paths: "200": description: OK schema: - $ref: '#/definitions/server.Status' + $ref: '#/definitions/prover_server.Status' summary: Get current prover server status swagger: "2.0" diff --git a/index.html b/index.html new file mode 100644 index 000000000..0ad42390a --- /dev/null +++ b/index.html @@ -0,0 +1,29 @@ + + + + + + Prover Server API + + +
+ + + diff --git a/prover/server/api.go b/prover/server/api.go index ec855b41e..48243238f 100644 --- a/prover/server/api.go +++ b/prover/server/api.go @@ -13,6 +13,17 @@ import ( "github.com/taikoxyz/taiko-client/pkg/rpc" ) +// @title Taiko Prover Server API +// @version 1.0 +// @termsOfService http://swagger.io/terms/ + +// @contact.name API Support +// @contact.url https://community.taiko.xyz/ +// @contact.email info@taiko.xyz + +// @license.name MIT +// @license.url https://github.com/taikoxyz/taiko-client/blob/main/LICENSE.md + // CreateAssignmentRequestBody represents a request body when handling assignment creation request. type CreateAssignmentRequestBody struct { FeeToken common.Address diff --git a/scripts/gen_swagger_json.sh b/scripts/gen_swagger_json.sh new file mode 100755 index 000000000..b1387d1e4 --- /dev/null +++ b/scripts/gen_swagger_json.sh @@ -0,0 +1,3 @@ +#/bin/sh + +swag init -g prover/server/api.go --parseDependency