Smithyプロジェクト

Smithyは、サービスとそれらが交換するデータを記述するためのインターフェース定義言語です。Smithyプロジェクトジェネレーターは、Smithyモデルを含むプロジェクトを作成します。

Smithyプロジェクトには2種類あります：

Service (--type=service) — サービスとその操作を定義するモデル。これはts#api --framework=smithyジェネレーターがTypeScript実装と一緒に作成するものです。
Shape library (--type=shapes) — 再利用可能なシェイプを定義するが、サービスは定義しないモデル。シェイプライブラリをSmithy プロジェクトに接続することで、各プロジェクトで定義を重複させるのではなく、プロジェクト間でシェイプを共有できます。

使用方法

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

yarn nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

npx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

bunx nx g @aws/nx-plugin:smithy#project --name=my-shapes --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - smithy#project
必須パラメータを入力
- name: my-shapes
クリック Generate

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	Smithyプロジェクト名
type	service \| shapes	service	作成するSmithyプロジェクトのタイプ。service（実装の準備が整ったサービスシェイプを持つモデル）とshapes（複数のSmithyプロジェクト間で共有される再利用可能なシェイプのライブラリ）から選択します。
serviceName	string	-	Smithyサービスの名前。デフォルトでは指定された名前を使用します。シェイプライブラリには適用されません。
namespace	string	-	Smithy APIの名前空間。デフォルトではモノレポのスコープを使用します。
directory	string	packages	Smithyプロジェクトが配置される親ディレクトリ。
subDirectory	string	-	Smithyプロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

Shape Library

Directorymy-shapes
- Directorysrc
  - main.smithy Your shared shape definitions
- smithy-build.json Smithy build configuration
- project.json Project configuration and build targets

シェイプライブラリはシェイプのみを定義します：

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

シェイプライブラリにはサービスがないため、そのsmithy-build.jsonはコード生成を設定しません — ビルドするとモデルを検証し、dist/<my-shapes>/build/model.jsonに単一のJSONモデルファイルとして組み立てます。

Service

Directorymy-service
- Directorysrc
  - main.smithy Your service definition
  - Directoryoperations
    echo.smithy An example operation
- smithy-build.json Smithy build configuration, including code generation
- ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
- project.json Project configuration and build targets

サービスモデルは、サービスシェイプとそれが公開する操作を定義します：

$version: "2.0"

namespace com.example

use aws.protocols#restJson1

@title("MyService")
@restJson1
service MyService {
    version: "1.0.0"
    operations: [
        Echo
    ]
}

サービスプロジェクトをビルドすると、OpenAPI仕様とTypeScript Server SDKがdist/<my-service>/build/に生成されます。

ビルド

SmithyプロジェクトはSmithy CLIでビルドされ、モデルを検証します：

pnpm nx build my-shapes

yarn nx build my-shapes

npx nx build my-shapes

bunx nx build my-shapes

macOSとLinuxでは、CLIはmiseによって解決され、ビルドがオンデマンドで取得するため、インストールする必要はありません — 初回ビルド時にピン留めされたバージョンをダウンロードしてキャッシュします。Windowsでは、自分でインストールする必要がある前提条件です — Windowsでのビルドを参照してください。

シェイプライブラリへの依存

シェイプライブラリをビルドすると、組み立てられたモデルがdist/<my-shapes>/build/model.jsonに書き込まれます。この単一ファイルには、ライブラリが定義するすべてのシェイプと、それが依存するすべてのシェイプが含まれているため、コンシューマーは直接参照するライブラリのみを宣言すればよいです。

別のSmithy プロジェクトからシェイプライブラリに依存するには、コンシューマープロジェクトに2つの変更を加えます：

コンシューマープロジェクトのsmithy-build.jsonのimportsに、ライブラリのビルドされたモデルを追加します。パスはそのファイルからの相対パスなので、../セグメントの数はコンシューマープロジェクトがどれだけ深くネストされているかに一致します — 以下のpackages/my-api/modelの場合は3つです：
```
{
  "version": "1.0",
  "sources": ["src/"],
  "imports": ["../../../dist/packages/my-shapes/build/model.json"],
  ...
}
```
コンシューマープロジェクトのproject.jsonのcompileターゲットの依存関係として、ライブラリのbuildターゲットを追加します。これにより、コンシューマーがビルドする前にモデルが存在するようになります：
```
{
  "targets": {
    "compile": {
      "dependsOn": ["@my-scope/my-shapes:build"],
      ...
    }
  }
}
```

これで、モデルはuseを使ってライブラリのシェイプを参照できるようになります：

$version: "2.0"

namespace com.example.api

use com.example.shared#Customer

structure GetCustomerOutput {
    @required
    customer: Customer
}

シェイプライブラリは、同じ方法で他のシェイプライブラリに依存できます。各ライブラリのビルドされたモデルには既に独自の依存関係が含まれているため、直接参照するライブラリに対してのみこれらの手順を繰り返す必要があります。複数のパスから到達するライブラリは一度だけ解決されます — Smithyは重複しているが同等のシェイプ定義を無視します。