SwaggerでHTTP APIのクライアントを10分で作成する方法

HTTP APIに対して複数のリクエストを行う必要がある場合、開発者は通常、通常の言語/フレームワークを使用して、コードにアナログカールをすばやく記述します：HTTPリクエスト、最小限のエラー制御、クエリまたはjson引数、jsonボディを文字列の形式のフィールド名で解析します。 これはすべて、プロジェクトが成長し始め、数回の呼び出しが数十回にならず、低レベルのコードの一部がコピーアンドペーストを開始するまで、うまく機能します。 それから-コピー＆ペーストによって生まれたバグの標準セットであり、開発者が徐々に時間を取り始めます。

Swagger / OpenAPIは、HTTP APIを操作するための「ハーベスター」の1つです。 これはAPI記述言語（最近はジェネレーターと仕様プロジェクトの組み合わせが行われました）、サーバーとクライアントのコードジェネレーター、ドキュメント、テスト-あらゆる種類の便利なものです。 カットの下で、OpenAPI記述をコンパイルし、数行のコードで会社のWebサイトにあるAPIの「人間」の記述を使用してPythonでクライアントを生成する方法を示します。 そして、そのようなクライアントは、手動で記述されたコードよりも優れているでしょう。

テスト対象としてVoximplant HTTP APIを使用する

Voximplant HTTP APIは5年以上前に当社によって作成されたもので、クラウドを完全に管理することができます。通話、ユーザーの操作、番号のレンタルと接続、通話の開始、その他、その他のシナリオを作成します。 開発者向けの管理パネルは、すべてAPIの上に作成されており、HTTPブラウザーリクエストのログを見ると、その使用方法をよく示しています。

たとえば、クラウドにJavaScriptコードをロードするエンドポイント/ AddScenarioを使用します。 このコードは、着信/発信コールで実行され、これらのコールを管理します（相互接続、音声の認識と合成、録音など）。 ドキュメントでは、HTTP APIは任意の動詞（GET、POSTなど）で使用でき、引数はURLエンコードまたはボディエンコードで渡すことができ、戻り値はドキュメント化されたフィールドを持つJSONであると書きました。 また、ほとんどのAPIは単一の認証スキームを使用します。アカウントID、名前、または電子メールを識別子として使用し、APIキー、パスワード、または一時セッションIDを確認として使用できます。

Swaggerを使用したHTTP APIについて説明します

公式サイトは仕様バージョン3.0で私たちに会っているという事実にもかかわらず、これはトリックです。 これまでのジェネレーターでは2.0しか使用できませんが、これを使用します。 Swaggerは、YAML形式またはJSON形式の説明をサポートしています。YAMLを使用してコードの量を減らします。 API記述の「導入」部分は、仕様のバージョンと、リクエストが行われるルートURLをキャプチャします。


エンドポイントについて説明します。


認可パラメータについて説明します。 自分で説明を作成する場合、可能なオプションから使用するものを説明するだけで十分です。 たとえば、アカウントIDとAPIキーで：


スクリプトの名前とコードを説明します。 サーバーはurlとbodyのパラメーターを等しく処理しますが、URLに12キロバイトまたは2キロバイトのテキストを含むリクエストを送信した場合、ネットワークインフラストラクチャが満足することはほとんどありません。 したがって、 scenario_scriptの場合 、本文を介した転送を厳密に規定します。


最後の仕上げは戻り値です。 すべてのAPIはJSONを返します。

swagger-codegenを使用してクライアントを生成する

結果のAPI記述ファイルを使用して、サーバー、ドキュメント、テストの生成など、多くの興味深いことができます。 クライアントを生成します！ たとえば、Python-Swaggerは、プログラミング言語とフレームワークの多数の組み合わせをサポートしています。 コードジェネレーターは、jarアーカイブとしてダウンロードし、プリインストールされたJavaを使用して実行するのが最も簡単です。


チームの結果は、 .md形式のドキュメント、カスタマイズされたテスト、展開、その他の優れた機能を備えた完全に完成したPythonプロジェクトになります。 あなたはすぐに仕事で試すことができます：

クライアントを生成する理由

生成されたクライアントは、まず第一に、エラー制御です。 すべての制限とオブジェクトを使用して（または他の誰かの）HTTP APIを記述した後、生成されたコードは呼び出しと使用法の正当性を検証します。 OpenAPI構文を使用すると、再利用可能なフラグメントを指定できるため、仕様内であっても繰り返し部分がコピーアンドペーストされません。

Swaggerは多くの言語とフレームワークを実行できるため、APIを説明すると、Python、Java、Ruby、PHP、Node.js、Android、iOS用の既製のクライアントが得られます。リストはかなり長く続きます。



HTTP APIの場合 、Swagger記述をJSON形式で生成します 。試してみるのが面白い場合は、 こちらから入手できます 。