Generate OpenAPI documentation #353
Conversation
tdeebswihart
force-pushed
the
tds/openapi-docs
branch
from
b3100e4
to
bc1084a
Compare
| @go install go.temporal.io/api/cmd/protogen@latest | ||
| @go install google.golang.org/protobuf/cmd/protoc-gen-go@latest | ||
| @go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest | ||
| @go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest | ||
| @go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest | ||
| @go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest | ||
| @go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest | ||
| @go install github.com/mikefarah/yq/v4@latest |
There was a problem hiding this comment.
Not necessarily in this PR, but I wonder if we want to use fixed versions here (or in a go.mod somewhere). I fear a newer OpenAPI gen will make slight alterations to the output that will cause CI to fail for someone that isn't even working on these. But not blocking or anything.
There was a problem hiding this comment.
I sure hope not. If we do we should discuss whether we want to pin the version of our protoc plugins as well. We already do for our server repo
There was a problem hiding this comment.
I could see some slight protoc-gen-openapi improvement making some tiny inconsequential output change resulting in CI break. But I am not worried (we can cross that road when we get there), but yes I do think we've learned we prefer fixed versions even if we're not the most mindful of upgrading.
tdeebswihart
force-pushed
the
tds/openapi-docs
branch
from
7b671c2
to
034ee87
Compare
What changed?
We now generate openapi v2 (swagger) and v3 specs as a part of proto compilation.
Why?
So that our customers can understand how to use our HTTP API
How did you test it?
Build and run temporalio/temporal#5393 (make start-dependencies + make start)