Automatically generate API documentation

[rhmdnd]

Initially, the compliance service is going to focus on exposing a gRPC API.

Can we find a tool that will generate the documentation for our API endpoints?

https://github.com/gendocu-com/grpc-docs/

[jhrozek]

I did a bit of research and haven't found anything better as long as we use a straight up grpc and not a swagger/openapi definition.

For a bit I played around with gnostic which is normally used to generate protobuf from openAPI, but together with its report tool, it should work the other way around, but I couldn't get the report tool to work for anything else than the example .pb files..

There's also protoc-gen-doc which works fine for protobufs, but not grpc..

[jhrozek]

at least the good thing about grpc-docs is that it's packaged as a docker container, so we could potentially add a make target that would just start the grpc-docs server..