Skip to content

Commit

Permalink
fix: swagger generation (#38)
Browse files Browse the repository at this point in the history
Closes: #35

The swagger generation consists of the following steps:
- generate json files from proto using the swagger plugin
- combine json files into client/docs/swagger-ui/swagger.yaml file
- embed client/docs/swagger-ui into go code using rakyll/statik
- serve this specific statik fs to `/swagger` endpoint
  • Loading branch information
tbruyelle authored Oct 28, 2024
1 parent 5c8e656 commit c445115
Show file tree
Hide file tree
Showing 12 changed files with 51,094 additions and 28 deletions.
1 change: 1 addition & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ run:
timeout: 5m
skip-dirs:
- tests/
- client/docs/statik

linters:
disable-all: true
Expand Down
16 changes: 13 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,20 @@ format: lint-fix
-not -name "*.pb.go" \
-not -name "*.pb.gw.go" \
-not -name "*.pulsar.go" \
-not -path "*client/docs/statik*" \
| xargs $(rundep) mvdan.cc/gofumpt -w -l

.PHONY: format lint lint-fix

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

update-swagger-docs: proto-swagger-gen
$(rundep) github.com/rakyll/statik -ns atomone -src=client/docs/swagger-ui -dest=client/docs -f -m

.PHONY: update-swagger-docs

###############################################################################
### Localnet ###
###############################################################################
Expand Down Expand Up @@ -286,11 +296,11 @@ protoImage=$(DOCKER) run --rm -v $(CURDIR):/workspace --workdir /workspace $(pro
proto-all: proto-format proto-lint proto-gen

proto-gen:
@echo "Generating Protobuf files"
@echo "--> Generating Protobuf files"
@$(protoImage) sh ./proto/scripts/protocgen.sh

proto-swagger-gen:
@echo "Generating Protobuf Swagger"
@echo "--> Generating Protobuf Swagger"
@$(protoImage) sh ./proto/scripts/protoc-swagger-gen.sh

proto-format:
Expand All @@ -303,7 +313,7 @@ proto-check-breaking:
@$(protoImage) buf breaking --against $(HTTPS_GIT)#branch=main

proto-update-deps:
@echo "Updating Protobuf dependencies"
@echo "--> Updating Protobuf dependencies"
$(DOCKER) run --rm -v $(CURDIR)/proto:/workspace --workdir /workspace $(protoImageName) buf mod update

.PHONY: proto-all proto-gen proto-swagger-gen proto-format proto-lint proto-check-breaking proto-update-deps
11 changes: 6 additions & 5 deletions app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (
"github.com/spf13/cast"

// unnamed import of statik for swagger UI support
_ "github.com/cosmos/cosmos-sdk/client/docs/statik"
_ "github.com/atomone-hub/atomone/client/docs/statik"

dbm "github.com/cometbft/cometbft-db"
abci "github.com/cometbft/cometbft/abci/types"
Expand Down Expand Up @@ -337,9 +337,7 @@ func (app *AtomOneApp) RegisterAPIRoutes(apiSvr *api.Server, apiConfig config.AP
nodeservice.RegisterGRPCGatewayRoutes(clientCtx, apiSvr.GRPCGatewayRouter)

// 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)
}
RegisterSwaggerAPI(apiSvr.Router)
}

// RegisterTxService allows query minimum-gas-prices in app.toml
Expand Down Expand Up @@ -397,7 +395,10 @@ func (app *AtomOneApp) setupUpgradeHandlers() {

// RegisterSwaggerAPI registers swagger route with API Server
func RegisterSwaggerAPI(rtr *mux.Router) {
statikFS, err := fs.New()
// NOTE(tb) the swagger fs has been registered under the `atomone` namespace
// (see `update-swagger-docs` in Makefile) to avoid conflicts with the legacy
// swagger fs registered in the default namespace.
statikFS, err := fs.NewWithNamespace("atomone")
if err != nil {
panic(err)
}
Expand Down
133 changes: 126 additions & 7 deletions client/docs/config.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,128 @@
{
"swagger": "2.0",
"info": {
"title": "AtomOne - gRPC Gateway docs",
"description": "A REST interface for state queries",
"version": "1.0.0"
},
"apis": []
"swagger": "2.0",
"info": {
"title": "AtomOne - gRPC Gateway docs",
"description": "A REST interface for state queries",
"version": "1.0.0"
},
"apis": [
{
"url": "./tmp-swagger-gen/atomone/gov/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "GovParams"
}
}
},
{
"url": "./tmp-swagger-gen/atomone/gov/v1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "GovV1Params",
"Proposal": "GovV1Proposal",
"Proposals": "GovV1Proposal",
"Vote": "GovV1Vote",
"Votes": "GovV1Votes",
"Deposit": "GovV1Deposit",
"Deposits": "GovV1Deposit",
"TallyResult": "GovV1TallyResult"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/auth/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "AuthParams"
}
}
},
{
"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/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/feegrant/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "FeegrantParams"
}
}
},
{
"url": "./tmp-swagger-gen/cosmos/upgrade/v1beta1/query.swagger.json",
"operationIds": {
"rename": {
"Params": "UpgradeParams"
}
}
}
]
}
16 changes: 16 additions & 0 deletions client/docs/statik/statik.go

Large diffs are not rendered by default.

Loading

0 comments on commit c445115

Please sign in to comment.