Document each services' API endpoints

[NimJay]

In Bank of Anthos, there is a README.md file for each microservice detailing the endpoints, environment variables, and other info about the respective microservice (e.g., see README.md for userservice).

We want to do something similar with this sample app (microservice-demo).

CC: @askmeegs

[polaroi8d]

It would be super great. If I would like to try the microservice-demo with simple docker-compose it'll be easier with this information.

[NimJay]

@polaroi8d, thanks for sharing that! It definitely helps validate the value of this work/issue. I've bumped the priority on this. :)

[NimJay]

@polaroi8d, I did want to clarify one thing though:

Even after we add this API/Endpoint documentation, we can't guarantee that this app (microservices-demo) will be compatible with docker compose. In other words, you could potentially run into roadblocks while composing your docker-compose.yml. Hope that's okay. :)

Also, in the meantime, the development guide might be useful.

P.S. - I have never used docker compose.

[polaroi8d]

@NimJay yea I know, it' okey. Thanks for mentioning that to me.

[bourgeoisor]

Commenting to reset OSLO. This is still something we should look at.

[donmccasland]

Nim, if we're not going to work on this before EOY, can we go ahead and close?

[jh409]

@donmccasland / @NimJay , what's your thoughts on adding autogenerated OpenAPI / Swagger documentation? There might be some inconsistencies between the different languages that wouldn't be present if the documentation was manually written, but the obvious upside is keeping the documentation in sync with the code.

I haven't looked in great detail but I assume we can tie that autogeneration into the local and remote build process.

I'm happy to pick up either automating it or doing it manually, as the API docs would help me too, but would appreciate the steer.

[NimJay]

My immediate thoughts:

• I am unfamiliar with OpenAPI, and I have very little experience with Swagger.
• I don't think introducing OpenAPI or Swagger is in conflict with the purpose of this repo, so we should explore it.
• I love the philosophy of keeping documentation as close to the source code as possible and I love self-documenting code, so your point about not having to keep documentation up-to-date resonates with me.
• That said, Online Boutique's gRPC APIs have not changed for years. So manually written documentation is totally okay. :)
• Next steps: I would love to understand
  • the best practices of OpenAPI/Swagger as they relate to gRPC.
  • how commonly OpenAPI/Swagger is used for gRPC. Is it an industry standard? Will users of Online Boutique find a showcase of OpenAPI/Swagger for gRPC useful/relatable?
  • the total engineering effort required (it sounds like a large effort). If it is a large effort, it might not be worth it.

Thank you, @jh409, for the great suggestion :)

[jh409]

I hadn't considered OpenAPI with gRPC, that's a good point. From initial searching, it looks like it's not a standard across the industry, although there are some tools that appear to perform the function.

~From what you've said, I'm leaning towards writing the documentation manually and having a quick investigation of the value vs. effort of automating after that.~

On further thought, I realised I was thinking about generating documentation for the Java, the Go etc. whereas what I should be considering is generating the documentation from the gRPC protos. I think that'd align better with the purpose of the repo; highlighting more gRPC goodness. I'll take a further look at https://github.com/pseudomuto/protoc-gen-doc

Thanks for the assist!

[minherz]

@NimJay can you please look into the issue when you are back? Looking at the discussion, it seems possible to narrow the scope and provide tangible requirements for a potential contributor.