Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update quickstart example with new gradle plugin and cli #2139

Merged
merged 3 commits into from
Feb 19, 2024
Merged

Update quickstart example with new gradle plugin and cli #2139

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0d07e63
Update quickstart example with new gradle plugin and cli
hpmellema Feb 14, 2024
9b255fe
Include groovy syntax for gradle example
hpmellema Feb 15, 2024
08ff2cf
Update docs/source-2.0/quickstart.rst
hpmellema Feb 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 118 additions & 64 deletions docs/source-2.0/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <namespaces>`.
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 <namespaces>`.

.. code-block:: smithy
:caption: model/weather.smithy

$version: "2"
namespace example.weather
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 }
Expand All @@ -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 }
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -413,6 +440,7 @@ service.


.. code-block:: smithy
:caption: model/weather.smithy

/// Provides weather forecasts.
@paginated(inputToken: "nextToken", outputToken: "nextToken",
Expand Down Expand Up @@ -442,51 +470,80 @@ 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 <cli_installation>`.
hpmellema marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: kotlin
To build a Smithy model using the :ref:`the Smithy CLI <smithy-cli>`,
create a :ref:`smithy-build.json <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.

configure<software.amazon.smithy.gradle.SmithyExtension> {
// Uncomment this to use a custom projection when building the JAR.
// projection = "foo"
}
.. tab:: Gradle

.. admonition:: Install required tools
:class: tip

Before you proceed, make sure you have `gradle installed`_.


To build a Smithy model using the :ref:`Smithy Gradle Plugin <smithy-gradle-plugin>`,
first, create a gradle build script file in the ``smithy-quickstart`` directory:

.. tab:: Kotlin

.. code-block:: kotlin
:caption: build.gradle.kts

// Uncomment to disable creating a JAR.
//tasks["jar"].enabled = false
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()
}


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 <http-traits>` to the API.
Expand All @@ -511,49 +568,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 <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 <output_directory>

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 <output_directory>

configure<software.amazon.smithy.gradle.SmithyExtension> {
// 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

Expand Down