Add dev apis UI with swagger-ui #2991
Conversation
|
|
||
| // TODO(agamez): remove these '/openapi.json' and '/docs' paths. They are serving a | ||
| // static 'swagger-ui' dashboard with hardcoded values just intended for develoment purposes. | ||
| // This docs will eventually converge into the docs already (properly) served by the dashboard |
There was a problem hiding this comment.
It's not clear to me how this openapi.json has hard-coded values... isn't it the same openapi.json that gets server by the frontend? More generally, why don't we just serve it like this permanently so it works both in dev as well as when deployed on the cluster? (I think a go binary is pretty efficient at serving a static file, but check).
Or is the issue rather the index.html (haven't checked the content, too large for the we UI so I assume it's just static webui for openapi)? If so, couldn't we still leave this permanently, but have the frontend handle the same path with the proper docs? So in devel, you get this one by default, but when configured on the cluster, this handler (for /docs) is never executed because the frontend already handles the path or similar?
There was a problem hiding this comment.
Thanks for your comments! Summarizing what we discussed offline:
-
The
openapi.jsonis not an additional file but simply the path in which the usual file (the one generated withbuf generate) is served. There is no problem in continue using this path in the future. In fact, it even makes more sense (since this component is responsible for its own docs, more cohesion) -
The issue is the
index.html: I wasn't able to simply use FileServer fromgwmux.Handlefunction (which takes a *runtime.HandlerFunc) without refactoring a little bit the code (see https://github.com/lstoll/grpc-rest-example/blob/master/go/server/main.go#L63)
So, IMHO this is a reasonable change considering the scope of this PR (just a temporary UI for playing around while this comp is under heavy development)
There was a problem hiding this comment.
Merging since the checks passed but wasn't properly notified back to github
Description of the change
This PR brings an easy way to test the API changes just using the generated OpenAPI v2 document. For doing so, this PR is embedding and serving a tuned up swagger-ui index.html.
apisUI.mp4
Benefits
Make developers happier :)
Possible drawbacks
N/A
Applicable issues
Additional information
Ideally, it (the makefile perhaps) should retrieve the latest swagger-ui version, perform the replacements, etc. But, given that it is a transient change, we shouldn't invest much time here, IMHO.