Project roadmap, documentation, samples, config etc

[simon-st]

I spent some time playing around with the smithy-kotlin-codegen. I realize it is still in an early stage, but I wanted to list some comments, questions and requests from the perspective of someone that tried to use the project without prior knowledge:

• What is the roadmap for this project? Do you have any idea when you will get close to a v1 release?
• No documentation. I had to figure out by trial and error how to use this plugin. It took me forever to even find the plugin name to use in the smithy-build.json. Just later, I found this documentation in a different repo that gives at least some information. It would be great if basic setup and use of the plugin was documented right here in this repo.
• Additional documentation would be appreciated as well. E.g. in what ways can the plugin be configured?
• A sample project would be nice to get started
• This might better be it's own ticket, but I was wondering if there is a way to configure the output classes. Specifically I would prefer the models to be data classes over the current builder pattern (or maybe both)

[aajtodd]

Thanks for this feedback!

Indeed it is still a work in progress with the primary use case currently being to support generation of AWS SDK for Kotlin service clients. This is intentionally a separate project though with the goal being to support generation of Kotlin clients (and perhaps one day server stubs) of any Smithy model (dependent on protocol support still of course).

What is the roadmap for this project? Do you have any idea when you will get close to a v1 release?

We do not have a good idea of when this will reach a v1 release. That being said whether it reaches v1 or not isn't as important as whether it's stable.

No documentation Additional documentation would be appreciated as well. E.g. in what ways can the plugin be configured?

Indeed we should port over (or just move) the referenced AWS SDK for Kotlin documentation on code generation to this repo. In addition we can look into improving the documentation. You might find the Smithy documentation on building models useful as an overview of how any smithy-* generator works.

Plugin settings are definitely an area to improve, the source is definitive right now but here is an example:

"kotlin-codegen": {
    "service": "com.company.foo#FooService",      // service ShapeId from model of to generate
    "package": {
        "name": "com.company.fooservice",         // root package name to use
        "version": "0.12.27",                     // library version
        "description": "Client for FooService"    // optional description of your library
     },
     "sdkId": "Foo", // this is a bit AWS specific controlling client naming (defaults to service shape name if unspecified)
      "build": {     // build settings, see source for a few more options
           "rootProject": true,
           "multiplatform": false,
           "generateDefaultBuildFiles": true
       }
}

A sample project would be nice to get started

Indeed this would be useful, the biggest barrier to having a meaningful example project is a protocol to use. Right now all of the protocol support is in AWS SDK for Kotlin. We have plans to eventually migrate the AWS protocol support to this repo at which point we could include a meaningful example.

This might better be it's own ticket, but I was wondering if there is a way to configure the output classes. Specifically I would prefer the models to be data classes over the current builder pattern (or maybe both)

There is some relevant discussion on why we chose builders over data classes here. That being said the constraints we face for AWS service clients may not be applicable to all users (e.g. you may be ok with breaking changes or you have fine grained control over your model that you can prevent the class of backwards compatibility issues we have to deal with). I think this would be a useful "mode" of code generation but we have no current plans to enable it. Please do feel free to make a ticket for this request.

---

We would be interested in hearing more about your use case if you could share any relevant details.

[simon-st]

Thanks for the extensive explanation. The linked discussion about data classes vs builder is very insightful.

We are currently still evaluating what codegen to use. We are mostly interested in generating the models for the client, so Smithy might be too much overhead since it requires a service plus protocol.

The most important feedback I wanted to give is that, without any prior knowledge of Smithy or the AWS services, it is very hard to get started. It's a big, complex topic and the documentation seems insufficient. Again, I understand that you are still in the midst of development. I will keep an eye on the project for sure to see where it goes.

[ianbotsf]

We are mostly interested in generating the models for the client, so Smithy might be too much overhead since it requires a service plus protocol.

Do you mean you're primarily interested in generating data structures from the model but not necessarily any serialization/deserialization for transmitting them to/from services?

[simon-st]

Correct. For now at least. I will need codegen for kotlin, swift and typescript. The Smithy plugins for those languages don't seem to be ready for primetime outside of AWS services yet from how I see that. If I can just generate the models for now though, that would already help. Our backend team is providing smithy files that they use internally and I was hoping that I can use those for the client models as well.

[aajtodd]

since it requires a service plus protocol.

It requires a service but without a protocol it will spit out basically just a service definition + models. The reason it requires a service is that the code generator works off the concept of a "Shape closure", i.e. all of the shapes reachable within some defined closure. For client generation this is the service shape.

There isn't really a path defined to generate just models at this point (e.g. like protobuf). It would certainly be a good feature though. If the backend smithy models have a service shape then you could probably do what you want.

[github-actions[bot]]

This is a very old issue that is probably not getting as much attention as it deserves. We encourage you to check if this is still an issue in the latest release and if you find that this is still a problem, please feel free to provide a comment or open a new issue.