仕様ファーストで設計してモックにする

仕様ファーストとは、コードの前にOpenAPIドキュメントを作ることです。APIの内容を合意し、モックで試し、実際のサーバができたら同じドキュメントと照合します。 このチュートリアルでは、Alpenglowショップの仕様をワークスペースに追加し、ショップにまだないエンドポイントを設計し、両方をMac上のモックで提供し、実際のAPIのレスポンスを仕様と照合します。

• 所要時間：20分。
• 必要なもの：Echolotと、最初のワークスペースで作ったものや新しい空のワークスペースなどのワークスペース。
• 学べること：仕様ページ、リント、仕様に従うリクエスト、モック、OpenAPI仕様チェック。

1. 仕様を追加するCopy Anchor Link

デモショップは、仕様をhttps://demo.echolot.dev/openapi.yamlで公開しています。

1. Macに保存します。ターミナルで：

   テキストをコピー

   curl -o ~/Downloads/openapi.yaml https://demo.echolot.dev/openapi.yaml

   または、アドレスをSafariで開いてファイル › 別名で保存…を選びます。

2. ワークスペースのウインドウで、仕様に切り替えます（⌘3）。

3. 仕様ファイルを追加…を選び（空のページ、またはサイドバーの+メニューにあります）、openapi.yamlを選びます。コピーがワークスペースのspecsフォルダに入ります。

仕様はビジュアルエディタで開きます。サーバ、パスまたはタグでグループ化したエンドポイント、スキーマが表示されます。ツールバーのスイッチでビジュアルとコードを切り替えられます。どちらも同じテキストを編集し、保存されるのはそのテキストです。

2. ショップにないエンドポイントを設計するCopy Anchor Link

ショップは、店舗の一覧がほしいとします。誰かが実装する前に設計します。

1. ビジュアルエディタで、エンドポイントを追加を選びます。

2. 新規エンドポイントで、メソッドはGETのままにして、パスを/stores、概要をList stores、タグをCatalogと入力します。エンドポイントを追加を選びます。Echolotは、出発点として200レスポンスを持つオペレーションを追加します。

3. エンドポイントのエディタで、オペレーションIDをlistStoresにします。

4. コードで表示を選びます。エンドポイントのresponsesを、ボディと例に置き換えます。

   テキストをコピー

         responses:
           '200':
             description: The shop's stores.
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     type: object
                     required: [id, city]
                     properties:
                       id: { type: string }
                       city: { type: string }
                       address: { type: string }
                 example:
                   - { id: zrh, city: Zürich, address: Bahnhofstrasse 1 }
                   - { id: brn, city: Bern, address: Spitalgasse 4 }

編集は行うたびに保存され、⌘Zで取り消せます。ビジュアルでの編集は、触れた項目の行だけを変更するため、コメントを含むファイルのそれ以外の部分は、書いたままです。 詳しくは仕様の編集を参照してください。

3. 仕様をリントするCopy Anchor Link

ツールバーの問題ボタンには、緑のチェックと問題なし、またはエラーと警告の数が表示されます。

1. ボタンを選びます。問題ポップオーバーに、ドキュメントがOpenAPI仕様に従っていて、すべての参照が解決できることが表示されます。
2. 問題を確認するため、わざと壊してみます。コードで、ある行の$ref: '#/components/schemas/Product'を'#/components/schemas/Produkt'に変更します。ボタンが赤くなります。ボタンを選んで問題を選ぶと、エディタがその行にジャンプします。
3. 変更を取り消します（⌘Z）。

同じリントは、コマンドラインツールでCIでも実行できます。--strictは警告でも失敗し、--hintsはオペレーションIDがないなどのアドバイスを加えます。

echolot spec lint specs/openapi.yaml --strict

4. 仕様に従うリクエストを作るCopy Anchor Link

1. 仕様ツールバーで、リクエストを生成を選びます。リクエストの下にAlpenglow demo shopフォルダができ、タグごとのフォルダ（Catalog、Auth、Orders）と、List storesを含むすべてのエンドポイントのリクエストが入ります。
2. Catalog › List productsを見ます。URLは{{baseUrl}}/productsです。テストタブには、仕様から作られた2つのチェックがすでにあります。ステータスが200と等しい、そして、記述されたボディのJSON Schemaです。

フォルダは仕様に従います。後で仕様が変わると、仕様ツールバーのリクエストメニューに「Alpenglow demo shop」の変更を確認…が表示されます。仕様で追加、変更、削除された内容を一覧し、リクエストへのあなた自身の編集を上書きせずに反映します。OpenAPI同期を参照してください。

生成されたリクエストは{{baseUrl}}（rlは小文字）で始まります。次の2つのステップで値を設定します。

5. 仕様のモックを提供するCopy Anchor Link

1. モックに切り替えます（⌘4）。+メニューを開いて、Alpenglow demo shopのモックを選びます。
2. 開始を選びます（⌘R）。ツールバーに緑のドットとアドレスhttp://127.0.0.1:4010/v1が表示されます。4010番以降で最初に空いているポートと、仕様のサーバのベースパスです。
3. 環境で使用を選びます。Echolotは、{{baseUrl}}がモックのアドレスになる環境Mock: Alpenglow demo shopを作成して選択します。

設定カードには、モックのポート、ネットワーク上の他のデバイスに応答、各レスポンスの前の遅延、失敗の割合（挿入される500）、チェック：仕様に違反するリクエストを拒否（理由付きで400）があります。モックはウインドウを開いている間、動作します。

6. モックにリクエストを送るCopy Anchor Link

1. リクエストに戻って、Catalog › List storesを送信します。モックは、あなたの例にある2店舗を200で返します。ヘッダータブにServer: Echolot mockが表示されます。
2. Catalog › List productsを送信します。モックには例がないため、スキーマからボディを作ります。正しい形で、値はプレースホルダです。リクエストの2つのチェックはどちらも成功します。
3. List productsのパラメータに、値cheapestのsortを追加して送信します。モックは拒否し、query “sort”: not one of the allowed valuesという400を返します。仕様で許可されているのはname、price、-price、ratingです。パラメータを削除します。
4. Get a productに、ヘッダーPrefer: code=404を追加して送信します。モックは、代わりに記述されている404のproblem detailsで応答します。ヘッダーを削除します。

モックのページのログには、モックが応答したすべてのリクエストが、一致したオペレーションと問題とともに一覧されます。レスポンスカードでは、オペレーションが、すべてのリクエストに対して、記述されている別のステータスや例で応答するようにできます。 状態が必要な応答のためのJavaScriptルートは、スクリプトルートにあります。

7. 実際のAPIを仕様と照合するCopy Anchor Link

1. 環境ページで、変数baseUrlをhttps://demo.echolot.dev/v1にした環境Demoを追加し、ページヘッダーで選びます。
2. List productsを開き、テストタブのテストを追加を開いて、OpenAPI仕様を選びます。入力する項目はありません。返ってきたステータスについて仕様が記述しているスキーマと、ボディを照合します。
3. 送信します。3つのチェックがすべて成功します。実際のショップは仕様と一致しています。
4. List storesを送信します。実際のショップは404で応答します。このエンドポイントは仕様にしかないためです。それが仕様ファーストの考え方です。モックがあれば、今すぐそれを前提に開発を進められます。

同じチェックをCIで実行するには、フォルダをecholot runで実行し、そこでecholot mockでモックを提供します。

echolot mock specs/openapi.yaml --port 4010

次のステップCopy Anchor Link

• トラフィックから仕様を作る：すでに送っているリクエストから仕様を書き出します。
• モック：履歴から保存した例、遅延、失敗、ネットワークでの共有。
• echolot spec：checkは、フォルダが仕様より遅れているとCIを失敗させます。