1

Node と Express を使用して REST API を構築しようと考えており、ドキュメントを提供したいと考えています。これを手作業で作成したくありません。Swagger、RAML、および Api Blueprint/Apiary の形式で利用できるソリューションがあるようです。

私が本当に望んでいるのは、Swashbuckle または Microsoft が提供するソリューションを使用して .NET ランドで可能なように、API コードからドキュメントを自動生成することですが、強力な型付けとリフレクションによって可能になります。

JS の世界では、Swagger/RAML/Api Blueprint マークアップを使用して API を定義し、ドキュメントを生成して、そこからサーバーを足場にするのが正しいオプションのようです。前者は簡単に思えますが、後者についてはよくわかりません。これらすべてのオプションのサーバー コード生成について私が見たものは、非常に限られているようです。定義を簡単に更新できるように、自動生成されたコードを手動コードから分離する何らかの方法が必要ですが、それに関する兆候や議論は見たことがありません。それは克服できない問題のようには見えません (私は JS よりも .NET に精通しているので、簡単に何かを見落としている可能性があります)。一年前。

何かが欠けている/誤解されているかどうか、および上記の問題の解決策が存在するかどうかを誰かに教えてもらえますか?

4

2 に答える 2

4

swagger-node-expressの初期バージョンはまさにこれを行いました。ルート、モデルなどからいくつかのメタデータを定義すると、そこからドキュメントが自動生成されます。JavaScript がいかに動的であるかを考えると、メタデータをモデルに対して最新の状態に維持する必要があるため、これを使用するのは少し面倒でした。

早送りすると、最新のswagger-nodeプロジェクトは、ある意味で「コードからドキュメントを生成する」とインラインと見なすことができる代替アプローチを採用しています。このプロジェクト (およびjava の場合はswagger-inflector 、 python の場合は connexion) では、swagger 仕様がAPI の DSL であり、ルーティング ロジックが swagger ドキュメントで定義されているものによって処理されるというアプローチをとります。そこから、コントローラーを実装するだけです。

swagger 仕様を「コードのように」扱う場合、これは非常に効率的な方法です。すべてのルートを構築し、すべての入力変数を検証し、API をあなたのビジネス層。

swagger-codegenプロジェクトから入手できるものなどの真のコード生成は非常に効果的ですが、最初にサーバーを構築した後に、コードとの巧妙な統合が必要になります。その考慮事項は、上記の 3 つのプロジェクトのワークフローから完全に取り除かれています。

これがお役に立てば幸いです。

于 2015-10-12T00:24:02.243 に答える
1

API と動的言語に関する私の経験では、アクセントはコード生成ではなく検証にあります。

たとえば、コンパイル済み言語を使用する場合、API 仕様からアーティファクトを生成し、それを使用して正確性を確保します。ラウンド トリップは、具体的なクラスではなくインターフェイスの生成によってサポートされます。

動的言語では、仕様はテスト時に使用され、定義されたすべての API がカバーされていることと、応答が仕様に準拠していることの両方を保証します (私はポステルの法則のために要求を検証しない傾向がありますが、それも可能です)。 .

于 2015-10-11T17:00:55.713 に答える