[FEATURE] (type-safe-api) only require OpenApi Generator when API changes

[jstrunk]

Describe the feature

Enable generated type-safe-api code to optionally be committed to the repo and only run OpenAPI Generator when the api spec is modified.

Use Case

I've heard developers say they are hesitant to adopt type-safe-api because it adds a dependency on the JDK and maven and that could be an issue for their customers. By committing the generated code, only developers who modify the API spec will need those dependencies.

Proposed Solution

No response

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

PDK version used

0.23.47

What languages will this feature affect?

Typescript, Java, Python

Environment details (OS name and version, etc.)

macos

[abest0]

I believe this functionality could be helpful here in cases where one wants to provide a frozen API to a customer without passing on the additional dependencies.

I've seen cases where the team accepting the prototype consists of Data Scientists who have familiarity with Python and possibly some familiarity with JS/TS. When providing the full type-safe-api project as a deliverable (vs just the generated API), the customer must use JDK to even build the solution--this adds complexity to the delivered solution that's at odds with adoption.

I appreciate the commitGenerateCode option since it provides the ability to freeze/eject the API and just provide the generated assets.

[cogwirrel]

Thanks for your contribution @jstrunk! Great to have the commitGeneratedCode option :)

I guess the next step here would be to add some logic to the various build tasks to skip codegen, though this needs a bit of thought - we ideally need a way to check whether what's generated matches the model, so that if the model changes code will be regenerated. Perhaps we generate a hash of the model and write it to the filesystem (and commit that when commitGeneratedCode is true), then at build time we regenerate the hash and proceed with codegen if the hash has changed? It'd also be nice to proceed with codegen if any generated files are missing too.

[cogwirrel]

An additional note - we've replaced OpenAPI generator with our own nodejs code generation engine so there's no longer a dependency on Java and Maven for generating code. This means no java dependency at all for projects which use OpenAPI as the modelling language.

Sadly Java and Maven are still required for the Smithy build, but this still simplifies things as we'd only need to commit the .api.json and perhaps a hash of the smithy model to skip the Smithy build :) Code generation could proceed regardless as it's much faster now too :)