Smithyプロジェクト

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

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

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

Tip

実装を伴うAPIが必要な場合は、代わりにts#apiジェネレーターを使用してください。これはSmithyモデルプロジェクト_と_それを実装するTypeScriptサーバーを作成します。

使用方法

Smithyプロジェクトの生成

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

オプション

パラメータ	型	デフォルト	説明
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プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーター出力

type = shapes

シェイプライブラリ

• Directorymy-shapes

  • Directorysrc

    • main.smithy 共有シェイプ定義
  • smithy-build.json Smithyビルド設定
  • build.Dockerfile モデルをビルドして検証
  • project.json プロジェクト設定とビルドターゲット

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

$version: "2.0"

namespace com.example

structure Customer {
    @required
    id: String

    name: String
    email: String
}

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

type = service

サービス

• Directorymy-service

  • Directorysrc

    • main.smithy サービス定義
    • Directoryoperations

      • echo.smithy 操作の例
  • smithy-build.json コード生成を含むSmithyビルド設定
  • build.Dockerfile モデル、OpenAPI仕様、TypeScript Server SDKをビルド
  • project.json プロジェクト設定とビルドターゲット

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

$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プロジェクトはDockerを使用してビルドされ、Smithy CLIを実行してモデルを検証します：

pnpm

pnpm nx build my-shapes

yarn

yarn nx build my-shapes

npm

npx nx build my-shapes

bun

bunx nx build my-shapes

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

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

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

1. Smithyプロジェクトはコンテナ内でビルドされ、ビルドには名前付きビルドコンテキストとしてワークスペースルートが与えられます。コンシューマープロジェクトのbuild.Dockerfileに、独自のソースがコピーされる場所と並んでCOPYを追加します：

   # Copy project files
   COPY smithy-build.json .
   COPY src src
   COPY --from=workspace dist/packages/my-shapes/build/model/model.json deps/my-shapes.json

2. コピーしたファイルをコンシューマープロジェクトのsmithy-build.jsonのimportsに追加します：

   {
     "version": "1.0",
     "sources": ["src/"],
     "imports": ["deps/my-shapes.json"],
     ...
   }

3. ライブラリのbuildターゲットを、コンシューマープロジェクトのproject.json内のcompileターゲットの依存関係として追加し、コンシューマーがビルドする前にモデルが存在するようにします：

   {
     "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は重複しているが同等のシェイプ定義を無視します。