Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add Swagger docs #326

Merged
merged 4 commits into from
Aug 19, 2024
Merged

docs: Add Swagger docs #326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9487cd1
chore: start adding swagger docs
hacheigriega Jul 21, 2024
dc9792a
WIP: swagger doc
hacheigriega Jul 23, 2024
456e6a1
docs: add swagger docs
hacheigriega Aug 16, 2024
0b5dc48
docs: update swagger config
hacheigriega Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 90 additions & 7 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
#!/usr/bin/env make -f
###############################################################################
## Set Env Vars ##
###############################################################################
##########################################################################
## Set Env Vars ##
##########################################################################
export CGO_ENABLED=1
export VERSION := $(shell echo $(shell git describe --tags --always --match "v*"))
export COMMIT := $(shell git log -1 --format='%H')

###############################################################################
## Set Local Vars ##
###############################################################################
#########################################################################
## Set Local Vars ##
#########################################################################
LEDGER_ENABLED ?= true
BUILDDIR ?= $(CURDIR)/build
DOCKER := $(shell which docker)
Expand Down Expand Up @@ -185,7 +185,90 @@ proto-update-deps:
@echo "Updating Protobuf dependencies"
@buf mod update ./proto

.PHONY: proto-gen proto-fmt proto-lint proto-update-deps

############################################################################
### Documentation ###
############################################################################

protoVer=0.14.0
protoImageName=ghcr.io/cosmos/proto-builder:$(protoVer)
protoImage=$(DOCKER) run --rm -v $(CURDIR):/workspace --workdir /workspace $(protoImageName)
cosmosVer=$(shell go list -m github.com/cosmos/cosmos-sdk | sed 's/.* //')

SWAGGER_DIR=./swagger-proto
THIRD_PARTY_DIR=$(SWAGGER_DIR)/third_party
BINDIR ?= $(GOPATH)/bin
STATIK = $(BINDIR)/statik

proto-swagger-gen:
@make clean
@echo "Downloading Protobuf dependencies"
@make proto-download-deps
@echo "Generating Protobuf Swagger"
@$(protoImage) sh ./scripts/protoc-swagger-gen.sh
@echo "Generating static files for swagger docs"
$(MAKE) update-swagger-docs

proto-download-deps:
mkdir -p "$(THIRD_PARTY_DIR)/cosmos_tmp" && \
cd "$(THIRD_PARTY_DIR)/cosmos_tmp" && \
git init && \
git remote add origin "https://github.com/cosmos/cosmos-sdk.git" && \
git config core.sparseCheckout true && \
printf "proto\nthird_party\n" > .git/info/sparse-checkout && \
git fetch --depth=1 origin "$(cosmosVer)" && \
git checkout FETCH_HEAD && \
rm -f ./proto/buf.* && \
mv ./proto/* ..
rm -rf "$(THIRD_PARTY_DIR)/cosmos_tmp"

mkdir -p "$(THIRD_PARTY_DIR)/ibc_tmp" && \
cd "$(THIRD_PARTY_DIR)/ibc_tmp" && \
git init && \
git remote add origin "https://github.com/cosmos/ibc-go.git" && \
git config core.sparseCheckout true && \
printf "proto\n" > .git/info/sparse-checkout && \
git pull origin main && \
rm -f ./proto/buf.* && \
mv ./proto/* ..
rm -rf "$(THIRD_PARTY_DIR)/ibc_tmp"

mkdir -p "$(THIRD_PARTY_DIR)/cosmos_proto_tmp" && \
cd "$(THIRD_PARTY_DIR)/cosmos_proto_tmp" && \
git init && \
git remote add origin "https://github.com/cosmos/cosmos-proto.git" && \
git config core.sparseCheckout true && \
printf "proto\n" > .git/info/sparse-checkout && \
git pull origin main && \
rm -f ./proto/buf.* && \
mv ./proto/* ..
rm -rf "$(THIRD_PARTY_DIR)/cosmos_proto_tmp"

mkdir -p "$(THIRD_PARTY_DIR)/gogoproto" && \
curl -SSL https://raw.githubusercontent.com/cosmos/gogoproto/main/gogoproto/gogo.proto > "$(THIRD_PARTY_DIR)/gogoproto/gogo.proto"

mkdir -p "$(THIRD_PARTY_DIR)/google/api" && \
curl -sSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto > "$(THIRD_PARTY_DIR)/google/api/annotations.proto"
curl -sSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto > "$(THIRD_PARTY_DIR)/google/api/http.proto"

mkdir -p "$(THIRD_PARTY_DIR)/cosmos/ics23/v1" && \
curl -sSL https://raw.githubusercontent.com/cosmos/ics23/master/proto/cosmos/ics23/v1/proofs.proto > "$(THIRD_PARTY_DIR)/cosmos/ics23/v1/proofs.proto"

update-swagger-docs: statik
$(BINDIR)/statik -src=client/docs/swagger-ui -dest=client/docs -f -m
@if [ -n "$(git status --porcelain)" ]; then \
echo "\033[91mSwagger docs are out of sync!!!\033[0m";\
exit 1;\
else \
echo "\033[92mSwagger docs are in sync\033[0m";\
fi

statik: $(STATIK)
$(STATIK):
@echo "Installing statik..."
go install github.com/rakyll/statik@v0.1.6

.PHONY: proto-gen proto-fmt proto-lint proto-update-deps proto-swagger-gen update-swagger-docs docs

###############################################################################
## Tests ##
Expand Down
12 changes: 8 additions & 4 deletions app/app.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,6 @@ import (

"github.com/sedaprotocol/seda-chain/app/keepers"
appparams "github.com/sedaprotocol/seda-chain/app/params"
"github.com/sedaprotocol/seda-chain/docs"
"github.com/sedaprotocol/seda-chain/x/staking"
stakingkeeper "github.com/sedaprotocol/seda-chain/x/staking/keeper"
"github.com/sedaprotocol/seda-chain/x/tally"
Expand All @@ -141,6 +140,9 @@ import (
wasmstorage "github.com/sedaprotocol/seda-chain/x/wasm-storage"
wasmstoragekeeper "github.com/sedaprotocol/seda-chain/x/wasm-storage/keeper"
wasmstoragetypes "github.com/sedaprotocol/seda-chain/x/wasm-storage/types"

// Used in cosmos-sdk when registering the route for swagger docs.
_ "github.com/sedaprotocol/seda-chain/client/docs/statik"
)

const (
Expand Down Expand Up @@ -1073,7 +1075,7 @@ func (app *App) GetMemKey(storeKey string) *storetypes.MemoryStoreKey {

// RegisterAPIRoutes registers all application module routes with the provided
// API server.
func (app *App) RegisterAPIRoutes(apiSvr *api.Server, _ config.APIConfig) {
func (app *App) RegisterAPIRoutes(apiSvr *api.Server, apiConfig config.APIConfig) {
clientCtx := apiSvr.ClientCtx
// Register new tx routes from grpc-gateway.
authtx.RegisterGRPCGatewayRoutes(clientCtx, apiSvr.GRPCGatewayRouter)
Expand All @@ -1087,8 +1089,10 @@ func (app *App) RegisterAPIRoutes(apiSvr *api.Server, _ config.APIConfig) {
// Register grpc-gateway routes for all modules.
app.bmm.RegisterGRPCGatewayRoutes(clientCtx, apiSvr.GRPCGatewayRouter)

// register app's OpenAPI routes.
docs.RegisterOpenAPIService(Name, apiSvr.Router)
// register swagger API from root so that other applications can override easily
if err := server.RegisterSwaggerAPI(apiSvr.ClientCtx, apiSvr.Router, apiConfig.Swagger); err != nil {
panic(err)
}
}

// RegisterTxService implements the Application.RegisterTxService method.
Expand Down
129 changes: 129 additions & 0 deletions client/docs/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
{
"swagger": "2.0",
"info": {
"title": "Cosmos SDK - Legacy REST and gRPC Gateway docs",
"description": "A REST interface for state queries, legacy transactions",
"version": "1.0.0"
},
"apis": [
{
"url": "./tmp-swagger-gen/sedachain/wasm_storage/v1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "WasmStorageParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/app/v1alpha1/query.swagger.json"
},
{
"url": "./tmp-swagger-gen/cosmos/auth/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "AuthParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/authz/v1beta1/query.swagger.json"
},
{
"url": "./tmp-swagger-gen/cosmos/bank/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "BankParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/base/tendermint/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "BaseParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/distribution/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "DistributionParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/evidence/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "EvidenceParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/gov/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "GovParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/group/v1/query.swagger.json",
"operationIds": {
"rename": {
"TallyResult": "GroupTallyResult",
"Proposal": "GroupProposal"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/mint/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "MintParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/params/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "Params"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/slashing/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "SlashingParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/staking/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "StakingParams",
"DelegatorValidators": "StakingDelegatorValidators"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/tx/v1beta1/service.swagger.json",
"dereference": {
"circular": "ignore"
}
},
{
"url": "./tmp-swagger-gen/cosmos/upgrade/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "UpgradeParams"
}
}
}
]
}

13 changes: 13 additions & 0 deletions client/docs/statik/statik.go
View file
Open in desktop

Large diffs are not rendered by default.

Binary file added client/docs/swagger-ui/favicon-16x16.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added client/docs/swagger-ui/favicon-32x32.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
60 changes: 60 additions & 0 deletions client/docs/swagger-ui/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="swagger-ui.css" >
<link rel="icon" type="image/png" href="favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="favicon-16x16.png" sizes="16x16" />
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}

*,
*:before,
*:after
{
box-sizing: inherit;
}

body
{
margin:0;
background: #fafafa;
}
</style>
</head>

<body>
<div id="swagger-ui"></div>

<script src="swagger-ui-bundle.js"> </script>
<script src="swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {

// Build a system
const ui = SwaggerUIBundle({
url: "./swagger.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})

window.ui = ui
}
</script>
</body>
</html>
Loading
Loading