[open-api-gateway] Move generators from default to dedicated task

[sperka]

An example of adding a new endpoint/operation:

Workflow in current version

1. make changes in spec/smithy model
2. run npx projen that kicks off the generators
3. generated library has the changes, if you run build immediately, your code fails to build because you need to introduce a new lambda integration
4. implement the lambda integration into your API
5. build

Workflow in proposed version

1. make changes in spec/smithy model
2. run generate task for the project, which runs the generators, changes from generated package become visible
3. implement the lambda integration
4. build

Moving the generation of client libs into build will result in build failure if there is a change. Although I'm not sure if we should add this generate task into the build step as well (probably yes).

@cogwirrel any take on this?

[cogwirrel]

I like the idea of having code generation as a build step - I think the main benefit would be that you wouldn't need to check in any generated code/docs to version control - you could .gitignore them and know that they'd be regenerated for anyone else that checks out the repo, or in a pipeline.

I'd consider the build failing after you regenerate the code with a new operation as a "feature", with the build error guiding users on what to do next :)

I think the challenge with codegen as a build step is it's a bit harder to hook into the monorepo and set up dependencies - eg if there's no package.json for the generated typescript client, yarn is going to throw an error for other package.jsons that have the generated client as a dependency. It's also nice to still be able to manage configuration of the clients in projen, and reference things like package names programmatically.

I could potentially see a bit of a hybrid approach working - where the "shell" of the generated client projects are generated via npx projen but the code/docs are .gitignore'd and get "filled-in" as a build step?

[cogwirrel]

We now have type-safe-api which supersedes open-api-gateway and uses the hybrid approach mentioned above - code is generated at build time rather than during project synthesis :)