Context
The merge-swagger.sh script was originally created to merge separate Swagger specs from the onboarding and transaction modules into a unified spec. Since both modules have been consolidated into a single ledger component, the merge step is no longer necessary — swag init on the ledger component produces a complete spec directly.
Current pipeline
swag init generates ledger_swagger.json
merge-swagger.sh patches metadata (title, version, host, securityDefinitions), generates docs.go with embedded JSON, converts to YAML, and cleans up intermediates
Proposed pipeline
swag init --outputTypes json,yaml generates swagger.json, swagger.yaml, and docs.go directly — no post-processing
Changes needed
- Update
main.go swagger annotations:
@title → Midaz Ledger API (Unified)
@host → localhost:3002
@description → match current production description
- Add
@securityDefinitions.apikey BearerAuth
- Version should come from a single source (currently hardcoded in both
main.go and .env)
- Update
components/ledger/Makefile generate-docs target to call swag init directly instead of the merge script
- Delete
components/ledger/scripts/merge-swagger.sh
- Regenerate specs and verify output matches current production spec
Notes
swagger.go already supports runtime overrides via env vars (SWAGGER_TITLE, SWAGGER_HOST, etc.), so hardcoded defaults in annotations are safe
openapi.yaml (OAS 3.0) has no automated generation pipeline today — that's a separate concern
- The
jq dependency for doc generation can be dropped after this change
Context
The
merge-swagger.shscript was originally created to merge separate Swagger specs from the onboarding and transaction modules into a unified spec. Since both modules have been consolidated into a single ledger component, the merge step is no longer necessary —swag initon the ledger component produces a complete spec directly.Current pipeline
swag initgeneratesledger_swagger.jsonmerge-swagger.shpatches metadata (title, version, host, securityDefinitions), generatesdocs.gowith embedded JSON, converts to YAML, and cleans up intermediatesProposed pipeline
swag init --outputTypes json,yamlgeneratesswagger.json,swagger.yaml, anddocs.godirectly — no post-processingChanges needed
main.goswagger annotations:@title→Midaz Ledger API (Unified)@host→localhost:3002@description→ match current production description@securityDefinitions.apikey BearerAuthmain.goand.env)components/ledger/Makefilegenerate-docstarget to callswag initdirectly instead of the merge scriptcomponents/ledger/scripts/merge-swagger.shNotes
swagger.goalready supports runtime overrides via env vars (SWAGGER_TITLE,SWAGGER_HOST, etc.), so hardcoded defaults in annotations are safeopenapi.yaml(OAS 3.0) has no automated generation pipeline today — that's a separate concernjqdependency for doc generation can be dropped after this change