Webシステムの開発において、バックエンドとフロントエンドを分けて開発する場合、それぞれの開発で使用する共有ドキュメントとして、OpenAPI(Swagger) を使用するケースも多いかと思います。
ですが、OpenAPI の API仕様書は yaml または JSON で記述されており、これを作成するのは相当な手間がかかります。
また、性質上、１度作成して完了ではなく、プロジェクトが進むにつれて何度も何度も更新が入るため、ドキュメントを最新の状態に保つのは相当な労力が発生します。
（というか、メンテナンスコストの大きさから、初回作成以降は全く更新されずに実際の挙動との乖離が発生したままの状態がずっと続いている状態も珍しくないんじゃないかと思う。）
OpenAPI で定義した API仕様書をグラフィカルに表示して分かりやすく表現したり、API仕様書の記述を補助するサービスは色々ありますが、どれもデファクトスタンダードの地位を築いているとは言えず、「どんなやり方がいいんだろうか」と、プロジェクトごとに模索していく事も多いのではないかと思います。
今回のプロジェクトでも、どんなやり方で進めて行くのかいいかを検証し、結構いいやり方を見つける事ができました。
実際、クライアントやエンジニアの友人に紹介すると、結構いい反応が返ってきました。
先に結論を書いてしまうと、こんな感じで進める事にしました。
・Stoplight という OpenAPI を GUI ベースで作成できるサービスを使用する。yamlファイルのインポート/エクスポートができる
・モックサーバには Prism というアプリケーションを使用する。yaml ファイルを、そのままモックサーバとして使用できる。ローカルにてコマンド１発で起動可能。
以下、これらの技術セットを採用するまでの経緯および状況です。
状況
フロント側は地図に複雑な描画が必要なため、得意なベンダーに依頼。
バックエンドは自社で開発する。
バックエンドの基盤部分はできているものの、フロント側に提供するAPIは未作成で、設計も未完了。
簡単に言えば、バックエンド・フロントエンド共に未着手で、大まかな要件は決まっているものの、細かい部分はこれから決めて行く。
これから新規で作成していくため、モックサーバもインフラも用意されていない。
地図上に様々な情報を表示するにあたり、どんなデータが必要なのか、最適なフォーマットはどんな形なのか、という事もよく分からないので、フロント側を開発するベンダーと協業しながら進めて行く必要がある。
ベンダーは業務委託契約のような形でチームの内側に入ってもらうのではなく、完全にフロントエンド側を切り出して、受託開発の形を取ってもらう。
そのため、API仕様書無し、もしくは超ざっくりと「こんな感じで作っといて」といった適当な依頼で仕事をしてもらう事ができず、API仕様書は、きっちりとした内容が必要となる。
採用した技術について
１．Stoplight
OpenAPI を GUI ベースで作成できるサービス。
ごちゃごちゃ説明するよりも、見てもらった方が早いです。
※画像で紹介しているのは実際のプロダクトではなく、OpenAPIがサンプルとして提供している、ペットストアの APIをインポートした内容です。
APIに慣れ親しんだ人なら、何をやっているかが直感的に分かるのではないかと思います。
エンドポイント、HTTPメソッド、クエリパラメータ、レスポンスパラメータ等をGUIで記述する事ができます。
また、作成した APIを yaml ファイルとして使用する事ができます。
生成した yamlファイルは、他の OpenAPI プラグインでも実行可能です。
（画像は、VSCode プラグインの OpenAPI (Swagger) Editor を使用した時の内容です。）
yamlファイルを出力するだけでなく、既存の yaml ファイルをインポートする事も可能です。
一人で使う分には無料で使えますが、複数ユーザで参照・編集するには、有料プランに切り替える必要があります。
２．Prism
簡単に言えば、
『 yaml ファイルを、そのままモックサーバとして使用できるアプリケーション 』
これも見てもらった方が直感的に分かりやすいです。
こんな感じで、コマンドラインにて yaml ファイルを指定して実行すると、モックサーバが立ち上がります。（-p は、ポート番号）
以下、curl コマンドで実行した時の内容です。
こんな感じで、ソースコードや実行環境を用意せずとも、簡単にモックサーバを立ち上げる事ができます。
これだけでも素晴らしいツールですが、さらに嬉しい事に npm install で超簡単にインストールができます。
コマンドは、こんな感じです。
（詳細は公式サイトを参照してください）
// インストール
npm install -g @stoplight/prism-cli
// yaml ファイルからモックサーバを起動
prism mock swagger-petstore.yaml -p 4010
Docker も用意されていますが、別に環境を汚すわけでも node のバージョンにきつい縛りが入っているわけでもないので、ローカル環境にグローバルインストールして使用しています。
進め方の解説
API仕様書は Stoplight を使用して yamlファイルを作成。
これを開発チームとベンダー間にて、GitHub のリポジトリで共有する。
Stoplight にて作成した API仕様書は、OpenAPIの仕様に基づいているため、別にビューアーに必ずしも Stoplight を使用する必要がなく、ベンダーの好きに展開してもらう事もできる。
モックサーバの実行については、「Prism というアプリを使ってください。インストールと実行方法は、こんな感じです」と説明し、詳しい使い方は README にでも書いておく。
クライアントからの反応について
プロジェクトのメンバーに提案すると、「別のメンバーにも紹介しよう！」と良い反応があったので、別の開発チームにも向けてプレゼンをしてみました。
そこでも反応が良く、他のプロジェクトにも展開する事になりました。
Stoplight は別に必ず使わなくても良いのですが、Prismの「yamlファイルがそのままモックサーバになる」という機能は本当に凄いので、このアプリだけでも採用する価値はあるんじゃないかと思います。
まだ実際にベンダーと協業しての開発が始まっていないので実際の成果がどうなるかはこれからですが、何かあれば追記していきます。
おまけ
英語版も書いてみました。
コメント