Deploying Swagger UI for Bacen's Pix API

Two weeks before Pix went live, the Brazilian central bank published its API as a single openapi.yaml in a public repository. The spec was complete and well written. It just had no rendered form, so reading it meant downloading the file and pasting it into an editor.

I opened a pull request adding twenty-five lines of CI and one new file.

The shape of the fix

The workflow runs on every push to the default branch. One action renders openapi.yaml into a static Swagger UI bundle, and a second publishes that bundle to the gh-pages branch. No server, no hosting cost, nothing to operate. GitHub was already storing the spec and already serving Pages. The twenty-five lines just connect two things the repository had.

The point is not that the documentation exists. It is that it regenerates from the spec on every push, so it cannot drift from the contract it describes. A rendered copy someone refreshes by hand is a second source of truth waiting to disagree with the first. This one has no separate lifecycle to forget about.

Link the outcome, not the diff

The pull request did not only describe the result. I ran the same workflow on my own fork and linked the live page, so anyone reading could see the rendered spec before deciding whether twenty-five lines of YAML were worth taking.

A diff asks a reviewer to imagine an outcome. A link hands it to them. For a change this small, imagining it was most of the work, so removing that was most of the value.

What I learned

The pull request was never merged. A maintainer replied that the central bank had no policy for accepting community code, and five days later posted a link to the rendered spec, live. They had implemented it themselves. I suggested they also put the URL in the repository’s About panel, and they did that too.

The page is still up almost six years later, documenting the API behind a payment system most of Brazil now uses daily.

So I stopped counting merged pull requests as the measure of a contribution. Where a project has no route for outside code, the most useful thing to send is not a patch. It is a working demonstration, small enough that rebuilding it costs less than reviewing it.