🆘 💇 🏳️‍🌈 TypeScript、Swashbuckle、およびAutoRestを使用した完全な入力に向けて 🦐 👇🏿 🧖🏾

はじめに

この記事では、ASP.NET Web APIに基づくバックエンドとTypeScriptを使用して作成されたフロントエンドとの間で型付きメッセージングを実装する方法について説明します。これは、大規模プロジェクトで作業する場合に特に重要であり、チームが分散している場合はさらに重要です。たとえば、バックエンド開発者とフロントエンド開発者が異なるタイムゾーンの異なる場所で働いている場合、常に何かに連絡したり話し合ったりする機会はありません。この場合、変更の追跡は骨の折れる作業であり、多くの微妙なエラーを伴う可能性があります。

この記事の著者にとって、WPFとSilverlightによるフロントエンドの開発に携わった人にとって、大きな問題は静的型付けの欠如でした。「2」と「2」を追加する代わりに、「2」と「2を返す関数」を追加したか、jQueryラッパーの代わりにDOMオブジェクトを渡した回数。 JSLintなどの静的コードアナライザーの出現により、問題は多少緩和されましたが、TypeScriptは、特にチーム開発において真のブレークスルーとなりました。

問題の本質

TypeScriptは静的型付けを可能にする言語ですが、「錯覚」と呼ばれるものもあります（ habrahabr.ru/post/258957、habrahabr.ru/post/272055 ）。不思議なことに、批評家は一般的に安全でないシナリオとしてバックエンドで作業することを強調しています。

ただし、問題の本質は、以前および現在のTypeScriptでJavaScriptでフロントエンドアプリケーションを記述する場合、WCFにあったようなメタデータおよびクライアントコードの自動生成を操作するためのツールが存在しないという事実にあります。

メタデータ

WPF + WCFの経験に目を向けると、この点ですべてが非常に良好です。もちろん、一般的に言えば、データは常に型付けされていない形式で送信されますが、送信されると、データはほぼ最後まで型付けされたままで、反対側に送信される直前にのみ文字列またはバイナリストリームにシリアル化されます。反対側では、再び、彼らはタイプされたものにそれらを回す特定のクライアントになります。このようなクライアントの手で書かないで、複数のエラーをキャッチしようとしないために、メタデータが存在します。 .NETの世界では、90％のケースで、それらを生成したり処理したりする作業はまったく必要ありません。サービスを書くだけで、適切なエンドポイントを追加することを忘れずに、自動生成されたメタデータを取得します。また、ワンクリックでクライアントを生成し、その結果、入力されたメッセージを交換できます。

JavaScript / TypeScriptで単一ページアプリケーションを開発する場合、WCFはWeb APIに置き換えられます。かつては、Web APIのメタデータをすぐに生成する方法がなかった理由が多少驚きでした（ヘルプページのメタデータを考慮しない）。どうやらその答えは、Web APIからのデータの主な受信者はJavaScriptコードであり、入力は意味をなさないということです。ただし、現在はJavaScriptではなくTypeScriptがあり、型付けされたデータを操作したいという要望が再び関連しています。

現在、非常に人気のあるメタデータ形式はOpenAPI / Swaggerです。当然のことながら、この形式でメタデータとドキュメントを生成する機会があります。

次に、型付き相互作用を整理するプロセスを示します。

つまり、次の手順に従います。

Swashbuckleライブラリを接続して構成する
ドキュメント/メタデータを生成する
生成されたファイルをバージョン管理システムに保存することの利便性を検証します
AutoRestを接続する
クライアントモデルを生成します
ビジネスでテストします。

スワッシュバックル

github.com/domaindrivendev/Swashbuckle

まず、メタデータを生成します。

そのため、Web APIがあり、その中に従業員との作業を担当するコントローラーがあるとします。

/// <summary> /// Gets all employees. /// </summary> /// <remarks> /// Gets the list of all employees. /// </remarks> /// <returns> /// The list of employees. /// </returns> [Route("api/employees")] [HttpGet] public Employee[] GetEmployees() { return new[] { new Employee { Id = 1, Name = "John Doe" }, new Employee { Id = 2, Name = "Jane Doe" } }; }

ご覧のとおり、Employee型の型付きオブジェクトの配列が返されます。プロジェクトを開始すると、従業員のリストをリクエストできます。

http：// localhost：1234 / api / employees

ここでSwashbuckleライブラリを有効にしましょう。 NuGetには2つのSwashbuckle.CoreおよびSwashbuckleパッケージがあります。 2つの違いは、1つ目はカーネルであり、マジックを実行するすべてのコードが含まれていることです。2つ目は、カーネルを構成するブートストラップをインストールする単なるアドオンです。

これはgithub.com/domaindrivendev/Swashbuckle#iis-hosted documentationに書かれています

Coreをインストールし、独自の構成コードを記述することをお勧めします。それを再利用する方が便利です。

インストールしましょう

 PM> Install-Package Swashbuckle.Core

WebActivatorExに登録する

 [assembly: WebActivatorEx.PreApplicationStartMethod(typeof(FullyTypedExample.WebApi.SwaggerConfig), "RegisterGlobal")]

また、構成コードを書きます

 /// <summary> /// Configures Swagger. /// </summary> /// <param name="config"> /// The Swagger configuration. /// </param> public static void ConfigureSwagger(SwaggerDocsConfig config) { config.SingleApiVersion("v1", "FullyTypedExample.WebApi"); config.IncludeXmlComments(GetXmlCommentsPathForControllers()); config.IncludeXmlComments(GetXmlCommentsPathForModels()); config.GroupActionsBy(apiDescription => apiDescription.ActionDescriptor.ControllerDescriptor.ControllerName); config.OrderActionGroupsBy(Comparer<string>.Default); config.PrettyPrint(); }

ここではすべてが非常に簡単です。最初に、APIのバージョンとタイトルを設定します。次に、コントローラーとモデルのxmlコメントを有効にする必要があると言います。 swagger-document内のアクションの順序とグループ化を調整します。 PrettyPrintオプションについても言及したいと思います。 SwaggerドキュメントのJSONフォーマットを有効にします。このオプションは、将来バージョン管理システムにドキュメントを保存し、差分ビューアーを使用してその変更を簡単に表示するために役立ちます。

これで、プロジェクトを開始してSwaggerインターフェースを確認できます。

http：// localhost：1234 / swagger

近くで、Swaggerドキュメント自体をJSON形式で見ることができます。

http：// localhost：1234 / swagger / docs / v1

ここで、生成されたドキュメントをバージョン管理システムに追加する必要があります。 Swashbuckleは内部でMicrosoft IApiExplorerを使用しているため、swaggerファイルを生成するには、Web APIを実行する必要があります（これについてはこちらgithub.com/domaindrivendev/Swashbuckle/issues/559 ）。つまり、ドキュメントを生成するたびに、Web APIを起動し、手動でswagger / docsをファイルにコピーする必要があります。もちろん、もっと自動化されたものが欲しいです。

自己ホスト型アプリケーションとしてWeb APIを起動し、非エンドポイントのswaggerリクエストを送信し、応答をファイルに書き込むことでこれを解決しました。 Swashbuckle構成コードを再利用すると便利でした。すべて次のようになります。

 /// <summary> /// Generate Swagger JSON document. /// </summary> /// <param name="filePath"> /// The file path where to write the generated document. /// </param> private static void GenerateSwaggerJson(string filePath) { // Start OWIN host using (TestServer server = TestServer.Create<WebApiHostStartup>()) { HttpResponseMessage response = server.CreateRequest("/swagger/docs/v1").GetAsync().Result; string result = response.Content.ReadAsStringAsync().Result; string path = Path.GetFullPath(filePath); File.WriteAllText(path, result); } }

すべてを実行してみましょう。

 nuget.exe restore "..\FullyTypedExample.sln" "C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe" "..\FullyTypedExample.WebApi.SelfHosted\FullyTypedExample.WebApi.SelfHosted.proj" /v:minimal "..\FullyTypedExample.WebApi.SelfHosted\bin\Debug\FullyTypedExample.WebApi.SelfHosted.exe" --swagger "swagger.json"

合計で、JSONファイルの形式のswaggerドキュメントを受け取り、バージョン管理システムに入れました。分散チームのフロントエンド開発者は、エンドポイントの変更を簡単に追跡できるようになりました。それがどのように見えるか見てみましょう。

従業員を識別子で取得するための新しいアクションを追加したとしましょう。

 /// <summary> /// Gets employee by id. /// </summary> /// <param name="employeeId"> /// The employee id. /// </param> /// <remarks> /// Gets the employee by specified id. /// </remarks> /// <returns> /// The <see cref="Employee"/>. /// </returns> [Route("api/employees/{employeeId:int}")] public Employee GetEmployeeById(int employeeId) { return this.GetEmployees().SingleOrDefault(x => x.Id == employeeId); }

そして、swagger.jsonを再生成しました。何が変わったのか見てみましょう

ご覧のとおり、このアクションに関するドキュメントが表示されており、diffビューアーを使用して簡単に確認できます。 PrettyPrintオプションのおかげで、フォーマットされていて読みやすくなっています。

AutoRest

これで、タスクの最初の部分は完了しました。メタデータがあります。クライアントパーツ、つまりクライアント側のデータの種類（サーバーから受信）

Web APIをリクエストするためのコード自体を生成できることを言わなければなりません。それはもう少し複雑で、コードジェネレーターを構成したり、独自のコードを記述したりするのに時間がかかる作業です。また、使用するライブラリ（jQuery、SuperAgent、または新しい実験的なFetch API developer.mozilla.org/en/docs/Web/API/Fetch_APIなど）とアプローチ（Promise、Rxなど）に大きく依存しますクライアントコード。

コード生成には、次のオプションがあります。

1. Swagger Code Generator github.com/swagger-api/swagger-codegen

Javaで記述されたSwaggerチームの公式ツールであり、適切なインフラストラクチャが必要です。 Dockerでも実行できます。確かに、JavaScriptの生成、特にTypeScriptは欠落しています。ただし、たとえばJavaでコードを生成する必要がある場合は、これがあなたの選択です。彼は明らかな理由で私たちに合わなかった。

2. Swagger JSライブラリ github.com/swagger-api/swagger-js

Swaggerチームの公式ツールでもあります。すでに暖かい。 JSで記述され、それに応じてJSコードを生成します。 npmまたはbowerを介してインストールされます。インフラストラクチャは私たちに適していますが、残念ながら、このタイプの世代は存在しません。

3. JSおよびTypescript Codegenに Swaggerする github.com/wcandillon/swagger-js-codegen

プロジェクトは、このアプローチの開発を始めた少し後に公開されました。おそらく近い将来、これが最適なソリューションになるでしょう。

4. ~~自転車~~コードジェネレーターを作成します。 全体として、なぜですか？しかし、まず最初に、AutoRestを試してみることにしました。うまくいかない場合、または機能に合わない場合は、ブラックジャックを使って独自に作成します。

5. AutoRest github.com/Azure/autorest

最後に、Azure MicrosoftチームのAutoRest。現在のバージョンは0.15.0であり、率直に言って、完全なリリースであると見なされるかどうかは明確ではありませんが、前のものと同様、Preマークは観察されません。一般に、ここではすべてが簡単で、必要な.d.tsファイルをインストールしてすぐに生成しました。

それでは、このツールを使用して私たちの旅の最終段階を見ていきましょう。

AutoRestはNuGetを介して接続します。

 PM> Install-Package AutoRest

パッケージは特定のプロジェクトには配置されず、ソリューションへのリンクが追加されます。

 <?xml version="1.0" encoding="utf-8"?> <packages> <package id="AutoRest" version="0.15.0" /> </packages>

パッケージには、実際に生成を実行するコンソールアプリケーションAutoRest.exeがあります。実行するには、次のスクリプトを使用します

 nuget.exe restore "..\FullyTypedExample.sln" "..\packages\AutoRest.0.15.0\tools\AutoRest.exe" -Input "swagger.json" -CodeGenerator NodeJS move "Generated\models\index.d.ts" "..\FullyTypedExample.HtmlApp\models.d.ts"

入力では、以前に生成されたswagger.jsonを送信し、出力では、models \ index.d.ts-モデルを含むファイルを取得します。クライアントプロジェクトにコピーします。

これで、TypeScriptには次のモデル記述があります。

 /** * @class * Initializes a new instance of the Employee class. * @constructor * Represents the employee. * @member {number} id Gets or sets the employee identifier. * * @member {string} name Gets or sets the employee name. * */ export interface Employee { id: number; name: string; }

実際に試してみましょう。

 public makeRequest() { this.repository.getEmployees() .then((employees) => { // Generate html using tempalte string this.table.innerHTML = employees.reduce<string>((acc, x) => { return `${acc}<tr><td>${x.id}</td><td>${x.name}</td></tr>`; }, ''); }); }

ここでは、idおよびnameモデルフィールドを参照します。サーバーへのリクエストの実装を意図的に下げました。既に述べたように、選択したライブラリとアプローチに依存する可能性があります。

存在しない年齢フィールドにアクセスしようとすると、TSコードはコンパイルされません。以前にアクセスしたフィールドがAPIで消えた場合、コードは再度コンパイルされません。新しいフィールドが追加されると、同じ差分を使用してすぐに表示されます。さらに、メタデータに基づいてJSDocドキュメントを自動的に受け取ります。一般に、静的型付けの魅力はすべて明白です。

ResponseType

興味深いことに、必要に応じて、ドキュメント化のために、返されるものとは異なるタイプを指定できます。たとえば、これは、型指定されていないDataSetで動作するレガシーコードがある場合に役立ちます。コントローラーからIHttpActionResultを返す場合。メソッドの実装に影響を与えることなく、ResponseType属性でそれらをマークし、特別な型を開発できます

 /// <summary> /// Gets all departments. /// </summary> /// <remarks> /// Gets the list of all departments. /// </remarks> /// <returns> /// The list of departments. /// </returns> [Route("api/departments")] [HttpGet] [ResponseType(typeof(DepartmentsResponse))] public DataSet GetDepartments() { var dataTable = new DataTable("Departments"); dataTable.Columns.Add("Id", typeof(int)); dataTable.Columns.Add("Name", typeof(string)); dataTable.Rows.Add(1, "IT"); dataTable.Rows.Add(2, "Sales"); var dataSet = new DataSet(); dataSet.Tables.Add(dataTable); return dataSet; }

クライアント側の型付きモデルを取得する

 /** * @class * Initializes a new instance of the Department class. * @constructor * Represents the department. * @member {number} id Gets or sets the department identifier. * * @member {string} name Gets or sets the department name. * */ export interface Department { id: number; name: string; }

問題

まず、models.d.tsファイルのサイズは時間とともに増加します。いくつかのサブファイルに分割することはまだ扱っていませんが、間違いなくこれを行う必要があります。

また、アンダースコアが使用されている場合など、非標準表記が使用されている場合、フィールド名の不正な生成に問題がある可能性があります。 C＃コードのLAST_NAMEフィールドは、SwaggerのlagT_NAMEで生成され、TypeScrptのlasTNAMEとして生成されます。

 /// <summary> /// Gets or sets the last name. /// </summary> [Required] // ReSharper disable once InconsistentNaming public string LAST_NAME { get; set; }

 "lasT_NAME": { "description": "Gets or sets the last name.", "type": "string" }

 export interface Employee { id: number; name: string; firstName: string; lasTNAME: string; }

マイナーな問題のほとんどは、構成を使用して簡単に解決でき、個別に言及する価値はありません。

おわりに

このアプローチにより、型付きメッセージ交換を整理することができました。同時に、彼はクライアントモデルのタイピングを提供し、クライアントコードとサーバーコードの不一致の可能性を減らし、APIとモデルの変更の追跡を容易にしました。素晴らしいボーナスは、RESTクライアントが組み込まれたAPIの便利な手動テストと、スキームに従ってオンザフライでペイロードを生成する機能でした。このアプローチを使用すると、バックエンド開発者とフロントエンド開発者の相互作用を改善するのにも役立ちました。

実用的な例をここで見ることができます。

github.com/EBTRussia/fully-typed-example

TypeScript、Swashbuckle、およびAutoRestを使用した完全な入力に向けて