From 0d07e63964cc26fbd555c04f13e3d39a2315e0ee Mon Sep 17 00:00:00 2001 From: Hunter Mellema Date: Wed, 14 Feb 2024 13:35:32 -0700 Subject: [PATCH 1/3] Update quickstart example with new gradle plugin and cli --- docs/source-2.0/quickstart.rst | 164 ++++++++++++++++++++------------- 1 file changed, 100 insertions(+), 64 deletions(-) diff --git a/docs/source-2.0/quickstart.rst b/docs/source-2.0/quickstart.rst index c9929747268..d9fd2f864b6 100644 --- a/docs/source-2.0/quickstart.rst +++ b/docs/source-2.0/quickstart.rst @@ -93,10 +93,31 @@ weather service. 4. This service closure contains the following operations: ``ListCities``, ``GetCity``, ``GetForecast``, ``GetCurrentTime``. -``Weather`` is a :ref:`service` shape that is defined inside of a -:ref:`namespace `. +First, create a directory called `smithy-quickstart` with a `model` directory +and a weather model file such that your `smithy-quickstart` directory has the +following file structure: + +.. code-block:: text + + smithy-quickstart/ + └── model/ + └── weather.smithy + +.. tip:: + + Run the following command to create the quickstart directory + + .. code-block:: text + + mkdir -p smithy-quickstart/model \ + && touch smithy-quickstart/model/weather.smithy \ + && cd smithy-quickstart + +Next, we will start to model a ``Weather`` service in the `weather.smithy` file. +``Weather`` is a :ref:`service` shape that is defined inside of a :ref:`namespace `. .. code-block:: smithy + :caption: model/weather.smithy $version: "2" namespace example.weather @@ -129,6 +150,7 @@ A resource is contained within a service or another resource. Resources have identifiers, operations, and any number of child resources. .. code-block:: smithy + :caption: model/weather.smithy $version: "2" namespace example.weather @@ -163,6 +185,7 @@ Each ``City`` has a single ``Forecast``. This can be defined by adding the ``Forecast`` to the ``resources`` property of the ``City``. .. code-block:: smithy + :caption: model/weather.smithy resource City { identifiers: { cityId: CityId } @@ -189,6 +212,7 @@ members of resource operations map to resource properties or identifiers to perform updates on or examine the state of a resource. .. code-block:: smithy + :caption: model/weather.smithy resource City { identifiers: { cityId: CityId } @@ -244,6 +268,7 @@ your API. Let's define the operation used to "read" a ``City``. .. code-block:: smithy + :caption: model/weather.smithy @readonly operation GetCity { @@ -291,6 +316,7 @@ Let's define the operation used to "read" a ``City``. And define the operation used to "read" a ``Forecast``. .. code-block:: smithy + :caption: model/weather.smithy @readonly operation GetForecast { @@ -332,6 +358,7 @@ bind the identifier of a ``City`` to its input structure; we are listing cities, so there's no way we could provide a ``City`` identifier. .. code-block:: smithy + :caption: model/weather.smithy /// Provides weather forecasts. @paginated(inputToken: "nextToken", outputToken: "nextToken", @@ -413,6 +440,7 @@ service. .. code-block:: smithy + :caption: model/weather.smithy /// Provides weather forecasts. @paginated(inputToken: "nextToken", outputToken: "nextToken", @@ -442,51 +470,62 @@ service. Building the Model ================== -Now that you have a model, you'll want to build it and generate things from it. -Building the model creates projections of the model, applies plugins to -generate artifacts, runs validation, and creates a JAR that contains the -filtered projection. The `Smithy Gradle Plugin`_ is the best way to get started -building a Smithy model. First, create a ``smithy-build.json`` file: +Now that you have a model, you'll want to build it and generate additional +artifacts from it. Building the model creates projections of the model, applies plugins to +generate artifacts, and runs validation. -.. code-block:: json +.. tab:: Smithy CLI - { - "version": "1.0" - } + .. admonition:: Install required tools + :class: tip -Then create a new ``build.gradle.kts`` file: + Before you proceed, make sure you have the :ref:`smithy-cli installed `. -.. code-block:: kotlin + To build a Smithy model using the :ref:`the Smithy CLI `, + create a :ref:`smithy-build.json ` file in the ``smithy-quickstart`` directory: - plugins { - id("software.amazon.smithy").version("0.6.0") - } + .. code-block:: json + :caption: smithy-build.json - repositories { - mavenLocal() - mavenCentral() - } + { + // Version of the smithy-build.json file specification + "version": "1.0", + // Location to search for Smithy model source files + "sources": ["model"] + } - dependencies { - implementation("software.amazon.smithy:smithy-model:__smithy_version__") - } + Next, run ``smithy build``. That's it! We just created a simple, read-only, ``Weather`` service. + +.. tab:: Gradle + + .. admonition:: Install required tools + :class: tip + + Before you proceed, make sure you have `gradle installed`_. - configure { - // Uncomment this to use a custom projection when building the JAR. - // projection = "foo" - } - // Uncomment to disable creating a JAR. - //tasks["jar"].enabled = false + To build a Smithy model using the :ref:`Smithy Gradle Plugin `, + first, create a ``build.gradle.kts`` file in the ``smithy-quickstart`` directory: + + .. code-block:: kotlin + :caption: build.gradle.kts + + plugins { + `java-library` + id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0") + } + + repositories { + mavenLocal() + mavenCentral() + } + + Next, run ``gradle build``. That's it! We just created a simple, read-only, ``Weather`` service. -Finally, copy the weather model to ``model/weather.smithy`` and -then run ``gradle build`` (make sure you have `gradle installed`_). Next steps ========== -That's it! We just created a simple, read-only, ``Weather`` service. - 1. Try adding a "create" lifecycle operation to ``City``. 2. Try adding a "delete" lifecycle operation to ``City``. 3. Try adding :ref:`HTTP binding traits ` to the API. @@ -511,49 +550,46 @@ There's plenty more to explore in Smithy. Complete example ================ -If you followed all the steps in this guide, you should have three files, laid -out like so:: - . - ├── build.gradle.kts - ├── model - │   └── weather.smithy - └── smithy-build.json -The ``smithy-build.json`` should have the following contents: +.. note:: -.. code-block:: json + You can clone a working version of this quickstart example using the + :ref:`Smithy CLI ` ``init`` command. - { - "version": "1.0" - } + .. tab:: Quickstart with Smithy CLI -The ``build.gradle.kts`` should have the following contents: + .. code-block:: -.. code-block:: kotlin + smithy init -o - plugins { - id("software.amazon.smithy").version("0.6.0") - } + .. tab:: Quickstart with Gradle - repositories { - mavenLocal() - mavenCentral() - } + .. code-block:: - dependencies { - implementation("software.amazon.smithy:smithy-model:__smithy_version__") - } + smithy init -t quickstart-gradle -o - configure { - // Uncomment this to use a custom projection when building the JAR. - // projection = "foo" - } +If you followed all the steps in this guide, your working directory should be laid out like so: + +.. tab:: Smithy CLI + + .. code-block:: text + + . + ├── smithy-build.json + └── model + └── weather.smithy + +.. tab:: Gradle + + .. code-block:: text - // Uncomment to disable creating a JAR. - //tasks["jar"].enabled = false + . + ├── build.gradle.kts + └── model + └── weather.smithy -Finally, the complete ``weather.smithy`` model should look like: +The complete ``weather.smithy`` model should look like: .. code-block:: smithy From 9b255fe1287ff00f534acf06bedc61b27b1a71aa Mon Sep 17 00:00:00 2001 From: Hunter Mellema Date: Thu, 15 Feb 2024 13:18:36 -0700 Subject: [PATCH 2/3] Include groovy syntax for gradle example --- docs/source-2.0/quickstart.rst | 40 ++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/source-2.0/quickstart.rst b/docs/source-2.0/quickstart.rst index d9fd2f864b6..d414bbeba26 100644 --- a/docs/source-2.0/quickstart.rst +++ b/docs/source-2.0/quickstart.rst @@ -505,20 +505,38 @@ generate artifacts, and runs validation. To build a Smithy model using the :ref:`Smithy Gradle Plugin `, - first, create a ``build.gradle.kts`` file in the ``smithy-quickstart`` directory: + first, create a gradle build script file in the ``smithy-quickstart`` directory: - .. code-block:: kotlin - :caption: build.gradle.kts + .. tab:: Kotlin - plugins { - `java-library` - id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0") - } + .. code-block:: kotlin + :caption: build.gradle.kts + + plugins { + `java-library` + id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0") + } + + repositories { + mavenLocal() + mavenCentral() + } + + .. tab:: Groovy + + .. code-block:: groovy + :caption: build.gradle + + plugins { + id 'java-library' + id 'software.amazon.smithy.gradle.smithy-jar' version '0.10.0' + } + + repositories { + mavenLocal() + mavenCentral() + } - repositories { - mavenLocal() - mavenCentral() - } Next, run ``gradle build``. That's it! We just created a simple, read-only, ``Weather`` service. From 08ff2cfd2d548cb2f3a1e583b9e51e71be7f11d7 Mon Sep 17 00:00:00 2001 From: Hunter Mellema <124718352+hpmellema@users.noreply.github.com> Date: Mon, 19 Feb 2024 10:17:02 -0700 Subject: [PATCH 3/3] Update docs/source-2.0/quickstart.rst Co-authored-by: Michael Dowling --- docs/source-2.0/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source-2.0/quickstart.rst b/docs/source-2.0/quickstart.rst index d414bbeba26..4f464314761 100644 --- a/docs/source-2.0/quickstart.rst +++ b/docs/source-2.0/quickstart.rst @@ -479,7 +479,7 @@ generate artifacts, and runs validation. .. admonition:: Install required tools :class: tip - Before you proceed, make sure you have the :ref:`smithy-cli installed `. + Before you proceed, make sure you have the :ref:`Smithy CLI installed `. To build a Smithy model using the :ref:`the Smithy CLI `, create a :ref:`smithy-build.json ` file in the ``smithy-quickstart`` directory: