chore: improve OpenAPI spec generation and add dev docs#114
chore: improve OpenAPI spec generation and add dev docs#114
Conversation
sallymoc
force-pushed
the
chore/openapi-indent-and-readme
branch
from
de9b33d to
06ce7b1
Compare
| - `protoc-gen-openapi` (`go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest`) | ||
| - `yq` - used for OpenAPI post-processing (`brew install yq` on macOS, `snap install yq` on Linux, | ||
| `choco install yq` on Windows, or [GitHub releases](https://github.com/mikefarah/yq/releases)) | ||
|
|
There was a problem hiding this comment.
@qubicmio I don't have linux but seems you are using the python-based version that has a different syntax. Please try 'snap install yq' that installs the Go-based mikefarah/yq v4+
There was a problem hiding this comment.
I made it work by using a different syntax but I don't think we should have such fragile constructs in our Makefile. It will work on some machines while it won't on others. Wouldn't it be better to have the conversion somewhere else in the pipeline?
There was a problem hiding this comment.
@qubicmio There are two different tools both called yq — the Go-based mikefarah/yq and the Python-based kislyuk/yq — with incompatible syntax. Can you confirm the last one is the one you have installed?
I've added a check-yq target in the Makefile that runs before openapi-v3-gen and detects if the wrong yq (or none) is installed, showing a clear error with install instructions.
As a next step, I could add a CI validation workflow that regenerates the OpenAPI spec and compares it with what's committed. If they differ, the PR fails with a message to run make openapi-v3-gen. We can also add it as a required check in branch protection so it blocks the merge until the YAML is up to date.
This is better than auto-generating the YAML after merge because:
- The developer sees the final YAML in the PR diff before merging, so reviewers can catch issues
- No surprise commits or merge conflicts from CI pushing changes back
- The committed YAML is always the source of truth
There was a problem hiding this comment.
I think it's the wrong place to handle this here because the yaml is correctly generated. only a certain user (ci pipeline or another repo idk in detail) needs a different format. I think the changes to the file should happen there so that the ease of development is not affected by tooling.
sallymoc
force-pushed
the
chore/openapi-indent-and-readme
branch
from
fc7c5dc to
65fa480
Compare
Remove yq post-processing from the Makefile and commit raw protoc output. OpenAPI adjustments (delete /health, /getEvents paths, tag modifications) are now applied on-the-fly in the CI workflow before dispatching the base64-encoded spec to consumer repos (integration, docs).
sallymoc
force-pushed
the
chore/openapi-indent-and-readme
branch
2 times, most recently
from
99485b1 to
e6de133
Compare
Fails the PR if the committed OpenAPI YAML doesn't match what protoc would generate from the current proto files.
sallymoc
force-pushed
the
chore/openapi-indent-and-readme
branch
from
e6de133 to
c12b266
Compare
3 participants
Uh oh!
There was an error while loading. Please reload this page.