Approach to documentation generator?

[jeberly]

First off, huge thanks to this library!! It looks like exactly what I was looking for after evaluating Twirp, et al. I love that it is simple, and right to the point with little dependencies and easy to grep the source. Keep up the good work.

Although RIDL is fairly self documenting (good job), has there been any thought into a doc generator with outputs eg. swagger, etc? Just interested in your thoughts/recommendations as I was thinking about potentially writing a generator to build docs we could publish for our API.

[pkieltyka]

thanks @jeberly :) really appreciate your enthusiasm, let me know if you guys actually try webrpc and how it works out for ya.

a doc generator is a great idea, and would be totally possible and could hook into the gen tools :) ie. instead of outputting ts/js/go/etc source -- generate docs

[pkieltyka]

See https://github.com/webrpc/gen-openapi#generate-openapi-3x-documentation :)

we can use the new gen-openapi by @VojtechVitek which allows you to generate openapi format from webrpc, and then use openapi to generate docs -- it works quite well

[VojtechVitek]

FYI, I recommend using https://github.com/webrpc/gen-openapi/tree/v0.6.0 tag.

I'm still iterating on the openapi generator and future webrpc-gen API and so the master branch is quite unstable right now.

[VojtechVitek]

I think this can be closed now. See https://github.com/webrpc/gen-openapi.

Starting with webrpc-gen v0.7.0, you can now generate OpenAPI 3.x (Swagger) spec file:

webrpc-gen -schema=./proto.ridl -target=openapi -out openapi.gen.yaml

And then generate documentation out of it.

[VojtechVitek]

There's more documentation now at https://github.com/webrpc/gen-openapi#generate-openapi-3x-yaml-file.

You can build a static HTML documentation or use Swagger UI / Editor.