Please invest time in better examples and documentation

[jabalsad]

Hi,

We'd love to test and use smithy, however the documentation makes getting started incredibly difficult. We'd love to see working examples of more complex use-cases (e.g. Smithy -> OpenAPI / API Gateway generation, different authorizer schemes, etc.). While the specifications themselves have some documentation, it's how they glue together that's the problem. I'm basically poking around in the dark to understand what it is I'm doing.

[mtdowling]

I'm glad you're interested in Smithy, and sorry that our docs aren't fully fleshed out yet. We're working on it. It sounds like you're interested specifically in how the OpenAPI conversion process works, so that helps us know where to focus in order to help you.

Our documentation and Smithy in general is still a work in progress. We are actively working on shipping client and server code generators for Smithy, along with docs and examples of how to use them, but delivering them will be spread over this year and next year.

[jabalsad]

Thanks. Some specific examples of setting up a (more complex) API Gateway using Smithy would be the first example I'm interested in. It would be great if the examples explore different authorization schemes too, because sometimes the devil is in the details. Also how such an application would play with deploying the APIG using CDK.

Another (perhaps unrelated point) is that we're interested in Go code generation, but it appears this is likely a library that is not maintained by your team; https://github.com/aws/smithy-go , but one which also lacks some documentation (perhaps because it is version 0.1.0).

I appreciate your continued effort to make it easier to use smithy.

[garretcharp]

Would really love to see how to use this with the CDK. Docs are still very lacking on any real examples :/

[mtdowling]

We've made major revisions to the Smithy website, spec, and code bases since this issue was opened. We've also recently launched the smithy-examples repo that is integrated with the Smithy CLI using smithy init to provide ready-made examples you can try out yourself. For example:

❯ smithy init --list
NAME                           DOCUMENTATION
----------------------------   -------------------------------------------------------------------------------
common-linting-configuration   Gradle project to create a package to define a common set of model validations.
custom-annotation-trait        Gradle project for creating a package for a custom annotation trait.
custom-linter                  Gradle project to create a custom, configurable model linter.
custom-string-trait            Gradle project for creating a package for a custom string trait.
custom-structure-trait         Gradle project for creating a package for a custom structure trait.
custom-validator               Gradle project to create a custom model validator.
decorators                     Gradle project to create a custom  decorator for validation events.
filter-internal-projection     Projection that filters out internal shapes and traits.
quickstart-cli                 Smithy Quick Start example weather service using the Smithy CLI.
quickstart-gradle              Smithy Quick Start example weather service using the Smithy-Gradle-Plugin.
shared-model-package           Gradle project to create a shared package of common Smithy models.
smithy-to-openapi              Generates an OpenAPI spec from a Smithy model

❯ smithy init -t quickstart-cli
Smithy project created in directory: quickstart-cli

Requests for more specific examples and use cases are welcome on the smithy-examples repo. I'll go ahead and close this since I don't think we'll ever stop working on making things better, including documentation, and there's now a better mechanism in place to request specific examples.