APIのテストと文書化でJSONスキーマを使用する

リファレンスAPI 2GISは 4年間開発されました。 JSONおよびXML形式でかなり大きく階層的に複雑な構造を返す約40のメソッドが登場しました。 ごく最近、私は経験を共有し、DevConfカンファレンスで講演することにしました。

レポートのトピックの1つは、参加者の間で最大の関心を呼び起こしました-APIを発行するための形式をテストするときのJSONスキーマの使用。 この記事では、このアプローチが解決する問題、制限があるもの、箱から出したもの、ボーナスとして提供されるものについて説明します。 行こう！







JSON-Schemaは、XMLスキーマ形式のJSON類似物です。 その本質は、宣言形式でドキュメントの構造を設定することです。 テスト目的でのJSONスキームの使用を妨げるものは何もありません。



APIのテストの難しさは何でしょうか？ これは洗練されたUIではありません。 考えてみて、リクエストを実行し、結果を予想された結果と比較してください。

要求または応答に含まれる可能性がある面倒な階層構造は動揺しています。 パラメータが約50の場合、考えられるすべての特性ケースを考慮することは非常に問題です。



APIがその責任を果たさなければならないという事実に加えて、あなたはそこから合理性と一貫性を期待します。 これはフォーマットにも適用されます。 数字は常に文字列ではなく数字として与えられるようにしたい。 配列が空の場合、nullであってはならない、または答えにまったく存在しないはずですが、空の配列にしてください。 もちろん、これらは些細なことですが、APIユーザーはそれらをためらうことを非常に不快に思います。 さらに、これは隠れたエラーにつながる可能性があります。 そのため、形式の厳格さに注意する必要があります。



一般に、構造と形式のテストは難しい作業ではありません。 メソッドごとに、JSONスキーマ形式を使用して要求と応答の構造を記述することができます。

彼らが言うように、すべてが私たちの前に発明されました。 あなたはそれを賢く使う必要があります。

API形式のテスト

リクエストとレスポンス

API応答の形式を正確にテストすることを検討します。 私たちに近いだけです APIは読み取り専用です。 ただし、APIが複雑なオブジェクトの形式でデータを受信できる場合、基本的なアプローチは読み取りの場合と同じです。

JSONスキーマ

書式



そのため、ハードビジネスJSON-Schemaで役立ちます。 フォーマット自体の簡単な紹介はすでにハブにあります したがって、私たちは些細な例に自分自身を制限します。 JSONオブジェクトを取得します。

{ "a":10, "b":"boo" }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

その構造、パラメーターのタイプ、コミットメントを設定するには、パラメーター値を特別なオブジェクトに置き換えるだけで十分です。 私たちは見ます：

 { "a": { "type": "number", "required": true }, "b": { "type": "string", "required": true } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

同意します、はっきりと。 概して、JSONスキーマは、XMLスキーマ形式に類似することを目指しています。



PHPの実装



もちろん、答えを記述するときにJSONスキーマを使用する必要はありません。 この形式は比較的新しく、完全に解決されたわけではありません。 XMLスキーマ形式ほど多くのライブラリとツールはありません。 しかし、非常に多くの開発者にとって、JSON形式ははるかに明確です。 また、PHPについて言えば、json_encode関数とjson_decode関数のおかげで、JSONはほとんどネイティブです。



JSON-Schema形式の実装は、 さまざまな言語用です 。 ご覧のとおり、選択は大きくありません。 MITとBerkeleyの 2つの研究所からのPHP用の2つのライブラリがあります。

執筆時点で、MITでの最後のコミットは2012年2月で、2013年6月にバークレーで行われました。そのため、クイックレビューによりバークレーは選択を迫られました。



軟膏のハエとして、答えのオブジェクトには、図に記載されているフィールドだけでなく、完全に残っているフィールドもあることに注意することができます。 さらに、答えは完全に有効であり、ほとんどの場合、これは受け入れられません。 私の意見では、これは特別なadditionalPropertiesプロパティをデフォルトでfalseに明示的に設定する小さなプリプロセッサによる誤解として扱われます。

検証

バトルにAPIレスポンスの検証を含めることはあまり意味がありません。余分なオーバーヘッドがあります。 しかし、テストを実行すると、これで終わりです。 モードを切り替えるには、アプリケーション構成ファイルのフラグで十分です。

特定のBerkeleyライブラリーについて話す場合、テストからの検証の例：

 $validator = new Validator(); $validator->check(json_decode($input), json_decode($schema)); //  $input    $schema $this->assertTrue($validator->isValid(), print_r($validator->getErrors(), true));
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

直感的にさえ、何が起こっているのか。



JSONスキームをチェックするためのテストを特別に記述する必要がないことに注意してください。 機能テストはすでにAPIで記述されていると考えています。 つまり、フィルタリングを有効にした場合、テストを実行すると、応答形式がバックグラウンドで自動的にチェックされます。 物事の間のように。 実際には、回路を書くこと以外の特別な努力は必要ありません。



はい、小さな追加：パフォーマンステストでは、「ヒント」がないように検証を無効にする必要があります。 また、開発者のマシンでは、逆に有効にして、フォーマットの違反をすばやく検出します。 質問-JSONスキームは誰が書くべきですか？ 開発者が書いているので、もっと便利です。 スキームはプロジェクトコード内に存在し、フォーマットが変更されると、開発者はすぐにスキームを修正します。

ドキュメント

テストを整理し、単体テストに接続し、出力で形式の正確性に自信を持っています。 しかし、私たちがやってきたJSONスキームを使用するときのもう1つの大きなボーナスは、APIドキュメントです。



ドキュメントには1つの問題があります-いまいましい、あなたはそれを書かなければなりません。 APIドキュメントはその仕様であり、すべてのニュアンスを反映する必要があります。 さて、他にどのように？ APIはそれ自体では存在せず、顧客が操作できるようにするためだけに存在します。 そして、あなたが彼に期待する驚きが少なくなればなるほど、それはより明確になり、ユーザーはそれをより速くより快適に使うことができます。 ドキュメントを保存できる唯一のケースは、APIの開発者が同時にそのユーザーである場合です。 そして、これは常にそうではありません。 したがって、ドキュメントの方が良いでしょう。 さて、パラメーターの総数が数百である場合、ドキュメントを最新の状態に保つ方法は？ テストでコードを書くだけでなく、ドキュメントに従う必要もあります。 要するに、プラスの「スマット」が1つあり、その中にはドキュメントがなくても十分です。

バージョニング

それでは、ドキュメントのバージョン管理についてはどうでしょうか？ 実際、私たちは多くの人と同じようにアプローチを採用しています-各機能はgitの別々のブランチで行われます。

まあ、各ブランチに独自のバージョンのドキュメントがある場合。 開発者とテスターの両方にとって、誰にとっても簡単です。 私はブランチでタスクを作成し、すぐにドキュメントを書き、タスクについて「忘れました」。



したがって、ドキュメントがコードとともに存在する場合に適しています。 また、異なるタスクから同じドキュメントをマージするのを便利にするために、特定のテキスト形式で保存するのが論理的です。 Markdown形式、セマンティックbbコード、またはその他の方法で保存できます。 しかし、実際には、さまざまな表、それらの間の関係、相互参照などを含む、ほとんど裸のテキストのままです。 ドキュメントの正確性をテストする方法は明確ではありません。 毎回、「病気になります」と慎重にすべてを手動で確認します。 これは第一に、そして第二に、エラーがまだ残っています。

JSONスキーマ

まあ、それでも：







それを拒否することは完全に不可能ですが、それをサポートするための労力を大幅に削減することは可能です。 すでにJSONスキーマがあります。 APIレスポンス、パラメーター間の階層関係、データ型、パラメーターバインディングにすべてのパラメーター名が既に含まれています。 つまり、この情報はドキュメントを生成するためにも必要です。



したがって、ブルドッグをサイと交差させ、ドキュメントをJSON-Schemaで直接記述することにしました。 JSONスキーマ形式には既に説明タグがあります。 しかし、仕様によると、文字列でなければなりません。 ただし、サンプル（ネストされたサンプルタグ）、およびシークレットパラメーター（ネストされた非表示タグ）などの特定のオプションも追加すると便利です。 したがって、これにはオブジェクトタグの方が適しています。 タグの名前として「メタ」を選択しました。 例：

 "reviews_count": { "type": "number", "required": true, "meta": { "description": " ", "hide": true } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

提出

ここで、JSONスキームを特別に設定します。 パーサー、そしてそれはエレガントなドキュメントに変わります。 ドキュメントを作成するとき、独自の「メタ」タグのコンテンツだけでなく、ネイティブスキーマタグからの情報も考慮されます。



ドキュメントの特定の表示方法は異なる場合があります。 間にリンクがある通常のフラットテーブルを優先しました。 しかし、これはもちろん理想的なオプションではありません。 ただし、ドキュメントをJSONスキームに配置しても、レンダリングの最終的な方法に拘束されることはないため、より自由になります。



最大限の柔軟性を得るために、ドキュメントを完全にJSONスキーマから構築しないでください。 ドキュメントの各ページに個別のテキストファイルがある場合、私たちのアプローチは証明されています。 そして、すでにその中に特定のJSONスキームへのリンクが挿入されています。 ページを構築するとき、JSONスキーマは最終的なテキストビューに変換されます。 したがって、ドキュメントに任意のテキスト、例、その他の資料を配置する問題を解決します。 同時に、できることをすべてJSONスキームにプッシュしようとはしていません。

自己診断

テストとドキュメントの両方に同じJSONスキームが使用されていることがわかります。 これは、JSONスキームが常に適切で正しいことを意味します。そうでない場合、テストは失敗します。 そのため、原則として、パラメーターの名前、そのタイプ、必須/オプション、有効な値のリスト、パラメーター間の階層関係に関連するドキュメントにエラーはありません。 おわかりのように、それだけでは十分ではありません。

例

ユースケースのないドキュメントは、APIユーザーのエントリしきい値を大幅に増加させます。 したがって、それらは必ず追加する必要があります。 以下のように整理します。 次に、ドキュメントで要求を説明し、回答の例を示します。



しかし、推測するのは難しくないので、応答テキストの関連性の問題が浮上します。 1週間が経ち、フォーマットは拡大します。そして、再び何を例にしますか？ より良い方法があります。



サンプルドキュメントのクエリ結果は動的である必要があるという結論に達しました。 ここでは異なるアプローチが可能です。 APIのレスポンスは非常に大きいことが多いため、特定の領域をクリックしてドキュメントに表示します。 この時点で、要求を満たします。 最も単純なスキームですが、データの受信にわずかな遅延があります。



このオプションが合わない場合は、特別なコマンドを使用して例のすべてのリクエストを動的に実行し、ドキュメントページに回答を記入できます。 これは、たとえばリリース前に行うことができます。



ところで、私たちはまだ例を書いているので、それらは一種の機能テストと考えることもできます。 実は、ドキュメント内のすべてのリクエストを収集し、JSONスキームをオンにして有効性をチェックします。 ただし、この方法では、壊れたメソッドまたは誤って構成されたクエリを特定できます。

空の値

形式の検証について言えば、応答に空の値を持つパラメーターをどう処理するかを決定する必要があります。 私たちは自分自身のために以下の合意に達しました。



いずれの場合でも、空の値が含まれている場合でも、パラメーターは応答に存在する必要があります。 そのため、回答の構造がわかりやすくなります。 調べるためだけにドキュメントを参照する必要はありません。



配列型パラメーターは空の配列を返します。 オブジェクトはヌルです。 数値および文字列パラメーターの場合、ゼロと空の文字列が意味のある値である場合、それらを返します。 たとえば、パラメータ「レビューの数」はゼロを返す場合があります-これは論理的です。 しかし、パラメータ「建物の階数」がゼロを返す場合、これはナンセンスです。 たとえば、特定の家の階数が不明な場合、nullが返されます。

nullが可能な場合とそうでない場合は、JSONスキームで明示的に示されます。 そして、それはドキュメントで意味します。 あなたのアプローチは異なる場合がありますが、主なことは、すべてのパラメーターで統一されていることです。そうしないと、APIのエンドユーザーは頭痛の種になります。

おわりに

JSON-Schemaは、貴重な時間のテストと文書化APIを大幅に節約します。 これは、ほんの少しの努力が多くの利益をもたらす場合に当てはまります。 また、APIが大きいほど、このアプローチはより多くの労力を節約します。



確かに、JSONスキームを使用するための小さなツールキットを作成するために投資する必要が生じた場合、



テストの時間を節約することに加えて、APIの下位互換性を維持するのが簡単です。 API形式は、JSONスキームで明確に表現されます。 また、大量のドキュメントが持ち越されます。