Do you have good examples where we could get an inspiration?
No, unfortunately, I can’t provide an example from some project.
As I can see, you are using protobuf for generation your web-services (e.g. https://github.com/SonarSource/sonarqube/blob/2b0f05f4442cb3e3b9c798adf9d93f64e19a6b01/sonar-ws/src/main/protobuf/ws-projects.proto#L50 )?
Maybe it is possible to add one more endpoint to your API (or extend existing /api/webservices/list ) to return information about response format in json schema format (https://json-schema.org/)?
One of the simple solutions - convert your *.proto files to JSONSchema and serve them as static files as you are doing with response_examples (e.g. https://github.com/SonarSource/sonarqube/blob/2b0f05f4442cb3e3b9c798adf9d93f64e19a6b01/server/sonar-server/src/main/resources/org/sonar/server/ws/ws/response_example-example.json).
Quick googling brought me to this tools:
- GitHub - chrusty/protoc-gen-jsonschema: Protobuf to JSON-Schema compiler
- GitHub - devongovett/protobuf-jsonschema: Compiles Protobuf IDL to JSON Schema
but I haven’t used them …
Off course, you may do this in runtime, but I’m not a Java-guy, so no tips from me in this question :-).
Alternative solution - maybe you have another network API, such as gRPC (since you are using proto-files)? This would be better for me as I won’t need to create a client library.