私がこれまで関わってきたどのAPIチームにも、二つのタイプが存在します。
一つは、OpenAPI仕様を手動で記述し、それをspecs/ディレクトリにコミットし、Gitを真の情報源として扱うチームです。もう一つは、ビジュアルデザイナーを操作して仕様を作成し、CIが文句を言ったときに仕様をエクスポートし、前回火曜日から蓄積された二つの表現間のずれをパッチで修正するチームです。
私は両方のタイプを経験してきました。前者は初日は遅いですが、90日目には速くなります。後者はその逆です。そして、約1ヶ月前まで、私が最もよく利用するAPIデザインツールであるApidogは、後者のタイプにしか対応していませんでした。そのビジュアルデザイナーは優れていますが、YAMLの往復変換は、コードレビューで擁護する必要がある機能でした。
しかし4月中旬、新規プロジェクトダイアログにスペックファーストモード（ベータ）が登場しました。私はローンチ日にあえてそれについて書きませんでした。まず実際のプロジェクトで使ってみたかったし、初期のバグが表面化するのに十分な期間を待ちたかったのです。1ヶ月というのは大体適切な期間です。この記事は、私のサイドプロジェクトのOpenAPI仕様に対してベータ版を半日使ってみてわかったことです。つまり、チームメイトが試す前に私が伝えるであろうこと、そしてそれがどこに適合し、どこに適合しないかについてです。
スペックファーストモードが実際に変えること
手短に言えば、Apidogには現在2つのプロジェクトモードがあり、その根本は全く異なる製品です。
デフォルトモードは、ほとんどの人が知っているものです。「+ 新規プロジェクト」をクリックすると、フォルダーとビジュアルフォームのツリーが表示され、フィールドを入力してエンドポイントを構築します。OpenAPI仕様は内部で生成されます。特にまだ強力なYAML習慣を持っていないチームにとっては機能します。
スペックファーストモードでは、フォームエディターが実際の.yamlおよび.jsonファイル用のリアルなコードエディターに置き換えられ、さらにGitリポジトリへの双方向同期が追加されます。OpenAPI仕様は、クリックのシリアル化ではなく、ディスク上のファイルそのものになります。構文ハイライト、OpenAPIスキーマに対するオートコンプリート、そして入力中にコードからサイドバーにエンドポイントの概要を構築する「リアルタイムディレクトリ解析」ペインがあります。
最後の点が、私が懐疑的な人にデモをする際にまず強調したいことです。ビジュアルデザイナーが存在する理由は、YAMLが難しいからではなく、YAMLが構造をスクロールするまで隠してしまうからです。Apidogのアウトラインビューは、ファイルを放棄することなくその問題を解決します。仕様を記述すれば、ナビゲーションが得られます。両者が画面上で共存するのです。
もしあるとすれば、その根底にある考え方はこうです。スペックファースト開発は、テキストエディタを好むことでは決してありませんでした。それは、成果物を誰が所有するかということでした。スペックファーストモードは、リポジトリ内のファイルを成果物として完全に扱います。UIはそれへの窓であり、ラッパーではありません。
セットアップ、エンドツーエンド
私がたどった手順は次のとおりです。Git認証のほとんどを含めても、10分もかかりませんでした。
1. 適切なモードでプロジェクトを作成します。 プロジェクト画面から、+ 新規プロジェクト → 一般 → スペックファーストモード。もし1年間オートパイロットでプロジェクトを作成してきたなら、このモード選択を見逃しがちです。一般モードは「推奨」と表示されており、目は2番目のタイルを素通りしてしまうでしょう。ここでは注意深く進んでください。
2. Gitリポジトリに接続します。 Gitリポジトリと接続までスクロールし、プロバイダーを承認します。私はGitHubを使用しましたが、ドキュメントには他のプロバイダーも記載されています。次に、Organization、Repository、およびMain branchを選択します。Apidogは、そのブランチ内の仕様ファイルをあなたの作業コピーとして同期します。
3. プロジェクトを設定します。 プロジェクト名を入力し、チームの権限を設定して、作成します。最初の同期で、リポジトリにある.yamlおよび.jsonファイルがApidogのワークスペースに取り込まれます。
4. 仕様をフォームとしてではなく、ファイルとして編集します。 いずれかのYAMLファイルを開きます。実際の編集機能、スキーマを認識するオートコンプリート、そして入力と同時にサイドバーにエンドポイントの概要が表示されます。OpenAPI拡張機能を使用してVS Codeで時間を費やしたことがあるなら、これはおなじみの感覚でしょう。ただし、アウトラインはナビゲーションに接続されており、エンドポイントをクリックすると適切な行にジャンプします。
5. コミットしてプッシュします。 右上にあるコミット＆プッシュをクリックします。ダイアログが開き、変更されたファイルをリストする変更点セクション、コミットメッセージフィールド、そしてプッシュまたはすべての変更を破棄の2つのボタンが表示されます。個別のステージングステップはありません。変更点にあるものはすべてコミットに含まれます。これは意図的な簡素化であり、ほとんどの仕様編集ワークフローにとっては正しい判断です。
6. 同期インジケーターを監視します。 左下隅に表示されます。図1では「Synced just now」（今すぐ同期済み）と表示されています。これは、ローカルの編集がプッシュされたか、プルされたか、リモートと同期がずれているかを示します。私はこれを画面の隅に表示したままにしていましたが、モーダルダイアログよりもこれを信頼するようになりました。インジケーターが緑色であれば、あなたとリポジトリは一致しています。
これが表面的なすべてです。6つのステップで、設定する別の同期エンジンも、インストールするプラグインもありません。
ドキュメントには書かれていない、私が気づいたこと
半日かけて試してわかった、注目すべき3つの点があります。
アウトラインビューの更新は、予想よりも速いです。これまでいくつかの「ライブOpenAPIエディタ」を使ってきましたが、そのほとんどは保存時に再解析するため、エンドポイントを追加してからサイドバーに表示されるまでに30秒ほどの遅延がありました。Apidogのアウトラインは入力中に更新され、ほぼ瞬時だったので、私は確認するのをやめました。これは些細なことのように聞こえますが、そうではありません。ナビゲーション補助としてアウトラインを信頼するか、ステータスレポートとして確認するかの違いです。
Git統合は本当に双方向です。Apidogを開いたまま、ローカルクローンで同じファイルを編集し、ターミナルからプッシュしました。Apidogはそれを検知し、同期インジケーターは「遅延」に変わり、ワンクリックでマージダイアログなしで変更がエディターにプルされました。ドキュメントが約束する双方向同期は、マーケティングの要約ではなく、実際の体験です。もしチームメイトがVim以外は使いたがらない場合でも、彼らはVimを使い続けられ、あなたはApidogを使い続けることができ、リポジトリ内のファイルが、両者が編集する唯一のものとなります。
同じプロジェクト内でビジュアルデザイナーに戻るエスケープハッチはありません。これは意図的なものですが、コミットする前に知っておく価値があります。プロジェクト作成時にスペックファーストモードを選択した場合、そのプロジェクトはスペックファーストになります。基盤となるデータモデルが異なるため、プロジェクトを途中で切り替えることはできません。同じ仕様で両方のモードを望むチームの場合、ワークフローは次のようになります。リポジトリに仕様を保持し、スペックファーストプロジェクトをそれに向け、ビジュアルモードのユーザーは同じソースからインポートする別のプロジェクトを開く、というものです。シームレスではありませんが、実用的です。
適合する点と適合しない点
私はこれを本番環境で使用するつもりです。それが私が提供できる最も直接的な答えです。実際の編集機能、OpenAPIスキーマを尊重するオートコンプリート、そして信頼できる同期インジケーターの組み合わせは、私がApidogに2年間求めていたものです。
しかし、これが誰のためのものか、正直なバージョンを以下に示します。
すでにOpenAPIを手動で記述している、または記述したい場合に適合します。CIがspectral lintを実行したり、仕様からクライアントSDKを生成したりして、仕様をどうしてもGitに置く必要がある場合に適合します。チームに、VS CodeからYAMLファイルに対してプルリクエストを送信するであろうエンジニアがいて、彼らのキーボードから離れさせずに全員が1つのツールに収束させたい場合に適合します。そして、「Apidog内の仕様」と「リポジトリ内の仕様」間のずれを、誰も信頼しないmake exportステップで管理してきた場合に、特によく適合します。
あなたのチームがOpenAPIに一度も触れたことがなく、ビジュアルデザイナーが貢献できる唯一の理由である場合には適合しません。そのようなチームにとっては、デフォルトモードが依然として正しい選択です。スペックファーストモードは、オンボーディングの容易さと引き換えに忠実さを提供しますが、貢献者のほとんどがAPIスペシャリストではない場合、そのトレードオフは間違っています。
また、同じプロジェクトで両方のモードを混在させる必要があるチームにとっては、まだ適合しません。この点については、ベータ版はまさにベータ版です。これは今後のいくつかのリリースで改善されると予想されます。
まとめ
かつてスペックファースト開発は、APIデザインツールを使わないことを意味していました。YAMLで作業し、テストランナーやモックサーバーを諦めるか、ビジュアルデザイナーで作業し、Gitを真の情報源として諦めるかのどちらかでした。スペックファーストモードにおける興味深い動きは、Apidogがもはや選択を迫らなくなったことです。
リポジトリ内のファイルは、エディター内のファイルです。アウトラインはビューであり、状態ではありません。Git同期はワイヤーであり、機能ではありません。APIプラットフォームがスペックファーストをエクスポートオプションとしてではなく、真剣に捉えるのを待っていたのであれば、これが試すべきものです。
ベータ版は本日、新規プロジェクトダイアログで利用可能です。Apidogをダウンロードし、作成時にスペックファーストモードを選択し、すでに信頼しているリポジトリを指定してください。最初のコミットは10分で完了します。それを維持するかどうかの決定には約1週間かかります。