Bradamant3
commented
3 years ago Agree +100. But (partly from Slack conversation):
only way to "guarantee" is to generate from code. We can do whatever we want with an OpenAPI definition (in this case, generate the docs from it), but since we don't design the API first, we need to generate it (yes, some people write it by hand, which pretty much moots the point of always being accurate ...). I haven't been able to find a go tool that does this. There are plenty of tools to generate go clients or servers from OpenAPI, but vice versa not so much. There's go-swagger but it supports only Swagger 2.0.
I thought OpenAPI 3.x had better doc support ... but it does not, it's pretty much the same as Swagger 2.0, so if docs are what we want, Swagger 2.0 might be sufficient. But if we're going to go to the trouble of generating Swagger/OpenAPI in the first place, might be nice for users to give them the definition file too, in which case current version would be better UX.
What I know about go tooling would fit in a thimble, though, so maybe someone else has better ideas. 🤞
github-actions[bot]
lahabana
It's tedious to manually update the reference documentation for the Kuma REST API, but there are a lot of REST API documentation generators available. It would be great to adopt something like OpenAPI so that we can guarantee the REST API documentation is always accurate and timely for each Kuma version.
xref #572 #553