Make it easy for people to modify the content API to their own needs

[mco-gh]

Proposal

If you try to use Emblem as a foundational framework, one of the first things you'll want to do is define your own backend API but the readmes and dir structure aren't really quite setup to make that process easy. We should have a well lit path to do this.

Additional context

Group chat excerpt with more details...

• Client library generation is a manual step. It seems like that should be part of the CI/CD flow so that if I update openapi.yaml to add a new param, it automatically regens the client lib and server, tests it, etc.
• When I run the api generator command it leaves the results in a dir named “openapi_client”, but the instructions and test code refer to a dir named “generated”. In docs/client-libs.md, the recommended generator command is prefixed by "rm -rf generated && ", which leads me to think it should be generating its output straight to the generated dir. But I see both dirs checked into github.
• If I have to guess, I suspect openapi_client dir is an anachronism, perhaps shouldn't be in the github repo, and I should use a generator command option that writes directly into the generated dir. Is that correct? tl;dr - should the documented generator command use "-o generated"?
• @charlie Engelke could you provide some input on this issue related to Emblem client library code generation?
• Hi Charlie, I tried using -o generated but realized it generates the same structure as the parent directory, which leads me to suspect that entire dir (client_libs/python) was created way back when via openapi-generator-cli. Is that correct? If so, then I think I'll need to generate my own client somewhere outside of that dir, and copy the contents of openai_client to the generated dir and check in the latter into my forked repo.
• It's been a long time since I looked at this. We did this API first, so that other components could use it, and therefore didn't want the using code still under development to have to generate the library. See https://github.com/GoogleCloudPlatform/emblem/blob/main/docs/decisions/2022-01-10-client-libraries.md for some background.
• https://github.com/GoogleCloudPlatform/emblem/blob/main/docs/decisions/2022-09-generated-client-library.md, which had effective been decided earlier.
• So the library was left in the repo for immediate use, or even importing directly from the repo itself, without a local copy. But as you saw in the doc, we said to regenerate a new one in its place, in case the openapi definitions were newer than it. (We also said that wouldn't happen, but since it could happen, maybe it would someday.)
• (welcome to someday!)
• Thanks Charlie, that makes sense. For now I'll work around this by creating my own version of the client_libs dir but I think eventually it would help to have a well lit path to modify the openapi spec and the generated artifacts because a typical use case will be to reuse emblem with a different content api.
• After my talk on the 12th, I'd be happy to work on this. If you like I can submit an issue and self-assign it.
• Btw, that docs/decisions directory is pure gold, thanks for the great initiative and discipline to do that!

[grayside]

Related: #169