chore: updating the swagger docs (#2055)

* WIP: adding cosmos,ibc swagger docs

* chore: remove cosmos and ibc-go swagger

* chore: add update-swagger docs as per release

* chore: removed statik and swagger-ui data

* move statik import to tools

* chore: updating release workflow and swagger docs section in readme

* chore: add update swagger docs to docker build action

* fix: fix the lint issue

* fix: fix the markdown lint

.github/workflows/release-umee-docker.yml

@@ -46,6 +46,11 @@ jobs:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate swagger docs 
+        run: |
+          make proto-swagger-gen
+          make proto-update-swagger-docs
 
       - name: Build and push
         uses: docker/build-push-action@v4

.github/workflows/release-umee.yml

@@ -29,6 +29,11 @@ jobs:
         run: echo "TM_VERSION=$(go list -m github.com/tendermint/tendermint | sed 's:.* ::')" >> $GITHUB_ENV
 
       # useful to test builds. However will require to add "push" rule to the "on" section
+      - name: generate and update swagger docs 
+        run: |
+          make proto-swagger-gen
+          make proto-update-swagger-docs
+      
       - name: goreleaser test-build
         uses: goreleaser/goreleaser-action@v4
         if: github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Enable:ReleaseBuild')

.gitignore

@@ -47,5 +47,10 @@ private*
 #IntelliJ
 .idea/
 
-#VsCode 
+#Vscode 
 .vscode
+
+# Swagger UI 
+swagger/statik/statik.go
+swagger/swagger-ui
+

Makefile

@@ -359,3 +359,8 @@ proto-lint:
 proto-check-breaking:
 	@echo "Checking for breaking changes"
 	@$(DOCKER_BUF) breaking --against $(HTTPS_GIT)#branch=main
+
+proto-update-swagger-docs:
+	@echo "Updating Protobuf Swagger Docs"
+	@if docker ps -a --format '{{.Names}}' | grep -Eq "^${containerProtoGenSwagger}$$"; then docker start -a $(containerProtoGenSwagger); else docker run --name $(containerProtoGenSwagger) -v $(CURDIR):/workspace --workdir /workspace $(protoImageName) \
+		sh ./contrib/scripts/protoc-update-swagger-docs.sh; fi

README.md

@@ -26,8 +26,11 @@ Umee will allow a multitude of decentralized debt products.
 - [Table of Contents](#table-of-contents)
 - [Releases](#releases)
   - [Release Compatibility Matrix](#release-compatibility-matrix)
-- [Active Networks](#active-networks)
+    - [Price Feeder](#price-feeder)
+    - [libwasmvm](#libwasmvm)
+  - [Active Networks](#active-networks)
 - [Build](#build)
+  - [Recommended Database Backend](#recommended-database-backend)
   - [Swagger](#swagger)
   - [Cosmovisor](#cosmovisor)
 - [Liquidators](#liquidators)
@@ -107,6 +110,25 @@ db_backend = "rocksdb"
 
 ### Swagger
 
+- To update the latest swagger docs, follow these steps
+
+Generate the latest swagger:
+
+  ```bash
+   $ make proto-swagger-gen
+   $ make proto-update-swagger-docs
+   ```
+
+Build the new binary or install the new binary with the latest swagger docs:
+
+   ```bash
+   $ make build
+   # or
+   $ make install
+   ```
+
+Make sure to execute these commands whenever you want to update the swagger documentation.
+
 - To enable it, modify the node config at `$UMEE_HOME/config/app.toml` to `api.swagger` `true`
 - Run the node normally `umeed start`
 - Enter the swagger docs `http://localhost:1317/swagger/`

contrib/scripts/protoc-swagger-gen.sh

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
-
 set -eo pipefail
 
-if ! [ -x "$(command -v swagger-combine )" ]; then
+if ! [ -x "$(command -v swagger-combine)" ]; then
   echo 'Error: swagger-combine is not installed. Install with $~ npm i -g swagger-combine' >&2
   exit 1
 fi
@@ -19,6 +18,7 @@ for dir in $proto_dirs; do
 done
 
 cd ..
+
 # combine swagger files
 # uses nodejs package `swagger-combine`.
 # all the individual swagger files need to be configured in `config.json` for merging

contrib/scripts/protoc-update-swagger-docs.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+SWAGGER_DIR=./swagger
+SWAGGER_UI_DIR=${SWAGGER_DIR}/swagger-ui
+
+# TODO: needs to fix merge issue of cosmos swagger and ibc-go swagger
+# SDK_VERSION=$(go list -m -f '{{ .Version }}' github.com/cosmos/cosmos-sdk)
+# IBC_VERSION=$(go list -m -f '{{ .Version }}' github.com/cosmos/ibc-go/v6)
+
+# SDK_RAW_URL=https://raw.githubusercontent.com/cosmos/cosmos-sdk/${SDK_VERSION}/client/docs/swagger-ui/swagger.yaml
+# IBC_RAW_URL=https://raw.githubusercontent.com/cosmos/ibc-go/${IBC_VERSION}/docs/client/swagger-ui/swagger.yaml
+
+# # download Cosmos SDK swagger yaml file
+# echo "SDK version ${SDK_VERSION}"
+# wget "${SDK_RAW_URL}" -O ./tmp-swagger-gen/cosmos-sdk-swagger.yaml
+
+# # download IBC swagger yaml file
+# echo "IBC version ${IBC_VERSION}"
+# wget "${IBC_RAW_URL}" -O ./tmp-swagger-gen/ibc-go-swagger.yaml
+
+SWAGGER_UI_VERSION=4.18.3
+SWAGGER_UI_DOWNLOAD_URL=https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_UI_VERSION}.zip
+SWAGGER_UI_PACKAGE_NAME=${SWAGGER_DIR}/swagger-ui-${SWAGGER_UI_VERSION}
+
+# if swagger-ui does not exist locally, download swagger-ui and move dist directory to
+# swagger-ui directory, then remove zip file and unzipped swagger-ui directory
+if [ ! -d ${SWAGGER_UI_DIR} ]; then
+  # download swagger-ui
+  wget ${SWAGGER_UI_DOWNLOAD_URL} -O ${SWAGGER_UI_PACKAGE_NAME}.zip
+  # unzip swagger-ui package
+  unzip ${SWAGGER_UI_PACKAGE_NAME}.zip -d ${SWAGGER_DIR}
+  # move swagger-ui dist directory to swagger-ui directory
+  mv ${SWAGGER_UI_PACKAGE_NAME}/dist ${SWAGGER_UI_DIR}
+  # remove swagger-ui zip file and unzipped swagger-ui directory
+  rm -rf ${SWAGGER_UI_PACKAGE_NAME}.zip ${SWAGGER_UI_PACKAGE_NAME}
+  # replacing default swagger with our generated swagger yaml file
+  sed -i 's+https://petstore.swagger.io/v2/swagger.json+./swagger.yaml+g' ${SWAGGER_DIR}/swagger-ui/swagger-initializer.js
+fi
+
+# move generated swagger yaml file to swagger-ui directory
+cp ${SWAGGER_DIR}/swagger.yaml ${SWAGGER_DIR}/swagger-ui/
+
+# install statik if not present
+go install github.com/rakyll/statik
+
+# generate statik golang code using updated swagger-ui directory
+statik -src=${SWAGGER_DIR}/swagger-ui -dest=${SWAGGER_DIR} -f -m
+
+# log whether or not the swagger directory was updated
+if [ -n "$(git status ${SWAGGER_DIR} --porcelain)" ]; then
+  echo "Swagger is updated"
+else
+  echo "Swagger in sync"
+fi

swagger/proto-config-gen.json

@@ -21,6 +21,30 @@
           "Params": "OracleParams"
         }
       }
+    },
+    {
+      "url": "./tmp-swagger-gen/umee/uibc/v1/query.swagger.json",
+      "operationIds": {
+        "rename": {
+          "Params": "UIBCParams"
+        }
+      }
+    },
+    {
+      "url": "./tmp-swagger-gen/umee/ugov/v1/query.swagger.json",
+      "operationIds": {
+        "rename": {
+          "Params": "UGovParams"
+        }
+      }
+    },
+    {
+      "url": "./tmp-swagger-gen/umee/incentive/v1/query.swagger.json",
+      "operationIds": {
+        "rename": {
+          "Params": "IncentiveParams"
+        }
+      }
     }
   ]
-}
+}

swagger/statik/init.go

@@ -0,0 +1 @@
+package statik

swagger/swagger.go

@@ -1,18 +1,22 @@
 package swagger
 
 import (
-	"embed"
 	"net/http"
 
 	"github.com/gorilla/mux"
-	"github.com/ignite/cli/ignite/pkg/openapiconsole"
-)
+	"github.com/rakyll/statik/fs"
 
-//go:embed swagger.yaml
-var Docs embed.FS
+	// unnamed import of statik for swagger UI support
+	_ "github.com/umee-network/umee/v5/swagger/statik"
+)
 
 // RegisterSwaggerAPI registers swagger route with API Server
 func RegisterSwaggerAPI(rtr *mux.Router) {
-	rtr.Handle("/swagger.yaml", http.FileServer(http.FS(Docs)))
-	rtr.HandleFunc("/swagger/", openapiconsole.Handler("umee", "/swagger.yaml"))
+	statikFS, err := fs.New()
+	if err != nil {
+		panic(err)
+	}
+
+	staticServer := http.FileServer(statikFS)
+	rtr.PathPrefix("/swagger/").Handler(http.StripPrefix("/swagger/", staticServer))
 }