四つの置き場所を一つのシステムに

Apifox は、インターフェースの一生をまとめて扱うツールです。ドキュメントを書き、デバッグし、バックエンドがまだ無い段階で Mock を作り、そのあとで自動テストを回します。その背後にある設計上の判断は、この四つの作業が同じデータを読むというものです。プロジェクトは一つのインターフェースについて説明を一つだけ保ち、ほかはすべてそこから導かれます。同じ API の二つの版を二つのシステムが持ってしまう、あのよく知られた問題を消しているのはこの点です。

提供元の説明は四つの領域を挙げています。API ドキュメント、API デバッグ、API Mock、API 自動テストです。公開されている SaaS 版は現在無料で、チームの人数、機能、プロジェクト数、インターフェース数に制限がありません。

ドキュメントを設計する

シナリオテストは、一連の呼び出しを一つの流れとして実行し、その間でやり取りされるデータが正しいかを確認します。アサーションはコードではなく画面上で設定し、変数は応答から抽出でき、流れの途中でデータベースに対して SQL を実行できます。事前・事後スクリプトは自由に書け、その構文は Postman のスクリプトと完全に互換です。そのツールから移ってくるチームにとって、学習の負担が低く保たれる理由です。

スクリプトは JavaScript に限りません。javascript、java、python、php、js、BeanShell、go、shell、ruby、lua を呼び出せるので、既にある小さな道具を別の言語に書き直す必要はありません。

デバッグ

デバッグ画面には、インターフェースツールとして期待されるものが揃っています。環境変数、事前・事後スクリプト、リクエストをまたいで共有される Cookie と Session です。さらに、応答のデータ構造をドキュメントの定義と突き合わせます。型が変わったフィールドや消えたフィールドは、一週間後に気づくのではなくその場で報告されます。

ケースはセッションではなくインターフェースに属します。一つのインターフェースに複数のケースを持て、それぞれに独自のパラメーターと期待値を持たせられます。アサーション、変数の抽出、SQL の操作もここで画面上から設定するので、設計、デバッグ、テストの作業の作法が同じままになります。

Mock と自動テスト

Mock に設定は要りません。ツールが API ドキュメントから妥当なデータを導きます。内蔵の Mock.js ルールエンジンにより、データ構造を定義する時点でルールを設定でき、パラメーターの値が違えば返す内容も変えられます。Mock が分岐の確認に使えるのは、この性質があるからです。順調な経路だけを試す道具ではありません。

自動テストは前述のシナリオテストをそのまま使います。Apifox CLI によってコマンドラインから起動できるので、継続的インテグレーションに収まります。Jenkins のジョブでも、ほかの実行環境でも、ビルドのたびにコレクションを流せます。

データベースと生成されるコード

データベースへのアクセスは両方向に使えます。データを読み取ってリクエストのパラメーターとして使うことも、リクエストが本当に成功したかを確認するために読むこともできます。インターフェースが短い確認だけを返し、実際の結果はテーブルに落ちる場合に効いてきます。

インターフェースやモデルの定義から、業務コードと API 呼び出しのコードの両方を生成します。TypeScript、Java、Go、Swift、Objective-C、Kotlin、Dart、C++、C#、Rust は対応する 130 の言語とフレームワークに含まれます。テンプレートを自作すれば、チームのアーキテクチャ規約に沿った出力にできます。

プロトコル、インポートとエクスポート

HTTP と HTTPS のインターフェースを管理でき、TCP 上の Socket 接続も扱えます。GraphQL、Dubbo、gRPC、WebSocket は今後の対応として示されています。ツールを標準にするかどうかを決める場面では、この点を先に知っておく価値があります。

エクスポートは OpenAPI（Swagger）、Markdown、HTML に対応します。インポートは OpenAPI（Swagger）、Postman、HAR、RAP2、JMeter、YApi、Eolinker、NEI、RAML、DOClever、Apizza、DOCWAY、ShowDoc、apiDoc、I/O Docs、WADL、Google Discovery を覆うので、既存のコレクションを手作業で作り直す場面はほとんどありません。

チームでの使い方

インターフェースのデータはクラウドで同期され、リアルタイムに更新されます。「一つのコピーだけを保つ」という考え方が複数人でも成り立つのは、この前提があるからです。権限はチーム単位とプロジェクト単位で管理し、管理者、一般メンバー、閲覧のみのメンバーという役割があります。

どんな人に向いているか

ドキュメント、デバッグ用のコレクション、テストケースを三か所で維持することに疲れたバックエンドのチームは、定義は一つ、使い道は複数という形をすぐに得られます。まだ存在しないインターフェースを待つフロントエンドのチームは、手書きの代用品ではなく、ドキュメントから導かれた Mock を受け取ります。すでに別の場所に大きなコレクションを持っているチームは、たいていは取り込めば済み、ゼロから作り直す必要はありません。