Skip to content

Remove merge-swagger.sh and simplify doc generation pipeline #1981

@gandalf-at-lerian

Description

@gandalf-at-lerian

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

  1. swag init generates ledger_swagger.json
  2. merge-swagger.sh patches metadata (title, version, host, securityDefinitions), generates docs.go with embedded JSON, converts to YAML, and cleans up intermediates

Proposed pipeline

  1. swag init --outputTypes json,yaml generates swagger.json, swagger.yaml, and docs.go directly — no post-processing

Changes needed

  • Update main.go swagger annotations:
    • @titleMidaz Ledger API (Unified)
    • @hostlocalhost: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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions