From 67e12837ccde7e35accfad2dae3d767dad395078 Mon Sep 17 00:00:00 2001 From: Hunter Mellema Date: Mon, 26 Feb 2024 12:18:20 -0700 Subject: [PATCH 1/2] Update quickstart example to use terse input/output syntax --- docs/source-2.0/quickstart.rst | 290 ++++++++++++++++----------------- 1 file changed, 138 insertions(+), 152 deletions(-) diff --git a/docs/source-2.0/quickstart.rst b/docs/source-2.0/quickstart.rst index ed0acf26b04..1c7e66097e2 100644 --- a/docs/source-2.0/quickstart.rst +++ b/docs/source-2.0/quickstart.rst @@ -89,12 +89,12 @@ weather service. 1. This service provides weather information for cities. 2. This service consists of ``City`` resources and ``Forecast`` resources. 3. The ``Weather`` service has many ``City`` resources, and a ``City`` - resource contains a single ``Forecast`` singleton resource. -4. This service closure contains the following operations: + resource contains a single ``Forecast`` resource. +4. This service and its resources contain the following operations: ``ListCities``, ``GetCity``, ``GetForecast``, ``GetCurrentTime``. First, create a directory called `smithy-quickstart` with a `model` directory -and a weather model file such that your `smithy-quickstart` directory has the +and a ``weather.smithy`` model file such that your `smithy-quickstart` directory has the following file structure: .. code-block:: text @@ -105,7 +105,7 @@ following file structure: .. tip:: - Run the following command to create the quickstart directory + Run the following command to create the quickstart directory and weather model file .. code-block:: text @@ -113,7 +113,7 @@ following file structure: && touch smithy-quickstart/model/weather.smithy \ && cd smithy-quickstart -Next, we will start to model a ``Weather`` service in the `weather.smithy` file. +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 @@ -158,7 +158,9 @@ identifiers, operations, and any number of child resources. /// Provides weather forecasts. service Weather { version: "2006-03-01" - resources: [City] + resources: [ + City + ] } resource City { @@ -182,7 +184,7 @@ the resource so that input members of the operation are used to provide the identity of the resource. Each ``City`` has a single ``Forecast``. This can be defined by adding the -``Forecast`` to the ``resources`` property of the ``City``. +``Forecast`` resource to the ``resources`` property of the ``City`` resource. .. code-block:: smithy :caption: model/weather.smithy @@ -191,7 +193,9 @@ Each ``City`` has a single ``Forecast``. This can be defined by adding the identifiers: { cityId: CityId } read: GetCity list: ListCities - resources: [Forecast] + resources: [ + Forecast + ] } resource Forecast { @@ -219,9 +223,20 @@ perform updates on or examine the state of a resource. properties: { coordinates: CityCoordinates } read: GetCity list: ListCities - resources: [Forecast] + resources: [ + Forecast + ] } + structure CityCoordinates { + @required + latitude: Float + + @required + longitude: Float + } + + structure GetCityOutput for City { $coordinates } @@ -272,37 +287,27 @@ Let's define the operation used to "read" a ``City``. @readonly operation GetCity { - input: GetCityInput - output: GetCityOutput - errors: [NoSuchResource] - } - - @input - structure GetCityInput for City { - // "cityId" provides the identifier for the resource and - // has to be marked as required. - @required - $cityId - } - - @output - structure GetCityOutput { - // "required" is used on output to indicate if the service - // will always provide a value for the member. - @required - @notProperty - name: String + input := for City { + // "cityId" provides the identifier for the resource and + // has to be marked as required. + @required + $cityId + } - @required - $coordinates - } + output := for City { + // "required" is used on output to indicate if the service + // will always provide a value for the member. + @required + @notProperty + name: String - structure CityCoordinates { - @required - latitude: Float + @required + $coordinates + } - @required - longitude: Float + errors: [ + NoSuchResource + ] } // "error" is a trait that is used to specialize @@ -320,21 +325,16 @@ And define the operation used to "read" a ``Forecast``. @readonly operation GetForecast { - input: GetForecastInput - output: GetForecastOutput - } - - // "cityId" provides the only identifier for the resource since - // a Forecast doesn't have its own. - @input - structure GetForecastInput { - @required - cityId: CityId - } + // "cityId" provides the only identifier for the resource since + // a Forecast doesn't have its own. + input := for Forecast { + @required + $cityId + } - @output - structure GetForecastOutput { - chanceOfRain: Float + output := for Forecast { + $chanceOfRain + } } .. admonition:: Review @@ -361,11 +361,12 @@ cities, so there's no way we could provide a ``City`` identifier. :caption: model/weather.smithy /// Provides weather forecasts. - @paginated(inputToken: "nextToken", outputToken: "nextToken", - pageSize: "pageSize") + @paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize") service Weather { version: "2006-03-01" - resources: [City] + resources: [ + City + ] } // The paginated trait indicates that the operation may @@ -374,22 +375,17 @@ cities, so there's no way we could provide a ``City`` identifier. @paginated(items: "items") @readonly operation ListCities { - input: ListCitiesInput - output: ListCitiesOutput - } - - @input - structure ListCitiesInput { - nextToken: String - pageSize: Integer - } + input := { + nextToken: String + pageSize: Integer + } - @output - structure ListCitiesOutput { - nextToken: String + output := { + nextToken: String - @required - items: CitySummaries + @required + items: CitySummaries + } } // CitySummaries is a list of CitySummary structures. @@ -398,7 +394,11 @@ cities, so there's no way we could provide a ``City`` identifier. } // CitySummary contains a reference to a City. - @references([{resource: City}]) + @references([ + { + resource: City + } + ]) structure CitySummary { @required cityId: CityId @@ -443,27 +443,23 @@ service. :caption: model/weather.smithy /// Provides weather forecasts. - @paginated(inputToken: "nextToken", outputToken: "nextToken", - pageSize: "pageSize") + @paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize") service Weather { version: "2006-03-01" - resources: [City] - operations: [GetCurrentTime] + resources: [ + City + ] + operations: [ + GetCurrentTime + ] } @readonly operation GetCurrentTime { - input: GetCurrentTimeInput - output: GetCurrentTimeOutput - } - - @input - structure GetCurrentTimeInput {} - - @output - structure GetCurrentTimeOutput { - @required - time: Timestamp + output := { + @required + time: Timestamp + } } @@ -623,30 +619,34 @@ The complete ``weather.smithy`` model should look like: .. code-block:: smithy $version: "2" + namespace example.weather /// Provides weather forecasts. - @paginated( - inputToken: "nextToken" - outputToken: "nextToken" - pageSize: "pageSize" - ) + @paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize") service Weather { version: "2006-03-01" - resources: [City] - operations: [GetCurrentTime] + resources: [ + City + ] + operations: [ + GetCurrentTime + ] } resource City { identifiers: { cityId: CityId } + properties: { coordinates: CityCoordinates } read: GetCity list: ListCities - resources: [Forecast] + resources: [ + Forecast + ] } resource Forecast { identifiers: { cityId: CityId } - read: GetForecast, + read: GetForecast } // "pattern" is a trait. @@ -655,28 +655,27 @@ The complete ``weather.smithy`` model should look like: @readonly operation GetCity { - input: GetCityInput - output: GetCityOutput - errors: [NoSuchResource] - } + input := for City { + // "cityId" provides the identifier for the resource and + // has to be marked as required. + @required + $cityId + } - @input - structure GetCityInput { - // "cityId" provides the identifier for the resource and - // has to be marked as required. - @required - cityId: CityId - } + output := for City { + // "required" is used on output to indicate if the service + // will always provide a value for the member. + @required + @notProperty + name: String - @output - structure GetCityOutput { - // "required" is used on output to indicate if the service - // will always provide a value for the member. - @required - name: String + @required + $coordinates + } - @required - coordinates: CityCoordinates + errors: [ + NoSuchResource + ] } // This structure is nested within GetCityOutput. @@ -701,22 +700,17 @@ The complete ``weather.smithy`` model should look like: @readonly @paginated(items: "items") operation ListCities { - input: ListCitiesInput - output: ListCitiesOutput - } - - @input - structure ListCitiesInput { - nextToken: String - pageSize: Integer - } + input := { + nextToken: String + pageSize: Integer + } - @output - structure ListCitiesOutput { - nextToken: String + output := { + nextToken: String - @required - items: CitySummaries + @required + items: CitySummaries + } } // CitySummaries is a list of CitySummary structures. @@ -725,7 +719,11 @@ The complete ``weather.smithy`` model should look like: } // CitySummary contains a reference to a City. - @references([{resource: City}]) + @references([ + { + resource: City + } + ]) structure CitySummary { @required cityId: CityId @@ -736,36 +734,24 @@ The complete ``weather.smithy`` model should look like: @readonly operation GetCurrentTime { - input: GetCurrentTimeInput - output: GetCurrentTimeOutput - } - - @input - structure GetCurrentTimeInput {} - - @output - structure GetCurrentTimeOutput { - @required - time: Timestamp + output := { + @required + time: Timestamp + } } @readonly operation GetForecast { - input: GetForecastInput - output: GetForecastOutput - } - - // "cityId" provides the only identifier for the resource since - // a Forecast doesn't have its own. - @input - structure GetForecastInput { - @required - cityId: CityId - } + input := for Forecast { + // "cityId" provides the only identifier for the resource since + // a Forecast doesn't have its own. + @required + $cityId + } - @output - structure GetForecastOutput { - chanceOfRain: Float + output := for Forecast { + $chanceOfRain + } } .. _examples directory: https://github.com/awslabs/smithy-gradle-plugin/tree/main/examples From a663c0eb67ebb999778ba4209f43881bfcc0f7b1 Mon Sep 17 00:00:00 2001 From: Hunter Mellema Date: Mon, 26 Feb 2024 13:05:06 -0700 Subject: [PATCH 2/2] Describe notProperty trait used in example --- docs/source-2.0/quickstart.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source-2.0/quickstart.rst b/docs/source-2.0/quickstart.rst index 1c7e66097e2..61df9fc818f 100644 --- a/docs/source-2.0/quickstart.rst +++ b/docs/source-2.0/quickstart.rst @@ -297,6 +297,8 @@ Let's define the operation used to "read" a ``City``. output := for City { // "required" is used on output to indicate if the service // will always provide a value for the member. + // "notProperty" indicates that top-level input member "name" + // is not bound to any resource property. @required @notProperty name: String @@ -646,6 +648,7 @@ The complete ``weather.smithy`` model should look like: resource Forecast { identifiers: { cityId: CityId } + properties: { chanceOfRain: Float } read: GetForecast } @@ -665,6 +668,8 @@ The complete ``weather.smithy`` model should look like: output := for City { // "required" is used on output to indicate if the service // will always provide a value for the member. + // "notProperty" indicates that top-level input member "name" + // is not bound to any resource property. @required @notProperty name: String