OAuth と複数のリビジョンの可能性と共に複数のクライアントで使用される Web サービスのバックエンドを構築するためのドキュメント ツールを検討してきました。私はすでに養蜂場について知っていましたが、少し調査を行ったところ、収益性の高い他のかなり優れたソリューションが見つかりました.
RAML は、優れたコード生成と API の再利用性を約束しているようです。しかし、モックサーバーを作成することはできないようです。また、apiblueprint を使用して REST API のクライアント側ライブラリとサーバー側スケルトンを生成できない理由がわかりません。
私たちにとって最良のユースケースは、コードを書くためのスケルトンを提供するノードエクスプレス/レスティファイアプリとともに、サービスを利用するためのクライアント iOS/Android/wp/js ライブラリを自動生成できる API のドキュメントです。API テストと負荷テストに加えて。
RAML/Swagger/Apiary のどのソリューションがこれに最適ですか?
サーバー スタブと API クライアントの両方を異なる言語で生成できるSwagger Codegen (無料、オープン ソース) を確認してください。
多くの企業/プロジェクトが本番環境で使用しています: https://github.com/swagger-api/swagger-codegen#companiesprojects-using-swagger-codegen
サポートされている言語/フレームワーク:
API クライアント: ActionScript、Bash、C# (.net 2.0、4.0 以降)、C++ (cpprest、Qt5、Tizen)、Clojure、Dart、Elixir、Go、Groovy、Haskell、Java (Jersey1.x、Jersey2.x、OkHttp 、Retrofit1.x、Retrofit2.x、Feign)、Node.js (ES5、ES6、Google Closure Compiler アノテーション付きの AngularJS) Objective-C、Perl、PHP、Python、Ruby、Scala、Swift (2.x、3.x )、Typescript (Angular1.x、Angular2.x、Fetch、jQuery、Node)
サーバー スタブ: C# (ASP.NET Core、NancyFx)、Erlang、Go、Haskell、Java (MSF4J、Spring、Undertow、JAX-RS: CDI、CXF、Inflector、RestEasy)、PHP (Lumen、Slim、Silex、Zend Expressive) )、Python (Flask)、NodeJS、Ruby (Sinatra、Rails5)、Scala (Finch、Scalatra)
API ドキュメント ジェネレーター: HTML、Confluence Wiki
免責事項: 私は、オープンソース プロジェクトへの最大の貢献者の 1 人です。
更新: 2018 年 5 月、約 50 人の Swagger Codegen のトップ コントリビューターとテンプレート作成者が、Swagger Codegen をフォークして、OpenAPI Generatorと呼ばれるコミュニティ主導のバージョンを維持することを決定しました。詳しくはQ&Aをご覧ください。
免責事項：養蜂場で働いています
私はそれが良い考えだとは思わない。
モック サーバーが必要であるということは、description-before-implementation のパスを受け入れたという事実を暗示しています。これは良いことです。
ただし、モックサーバーに対して開発すると、API設計を反復するという考え方です（これが、コードではなく「テキスト」ツールで行うことが理にかなっている理由の1つです）...そしてそれが難しい部分です.
スキャフォールディングをサポートする新しいツールがいくつかありますが、実際の問題は、ブループリントが更新された後にスキャフォールディングされたアプリを更新する方法です。一部の人々がこれに取り組んでいることは知っていますが、まだリリースされていません。
私の意見では、最善のアプローチは、モック化された API に対して実際のプロトタイプを開発して、結果のアプリの UX をテストすることです。設計がある程度安定したら、他のクライアントとサーバーの開発を開始し、最終的に元の設計を拡張します。
特定のユースケースに最適であるため、それぞれの言語にあるそれぞれのツールでテストします。実装が設計図 (別名、書面による契約) に準拠していることをテストするには、dredを使用できます。
その上で連携するツールは、保守が不可能な手動で拡張するライブラリを生成するのではなく、ブループリントを入力として使用する必要があります。
RAMLは、 API Designerでボタンを 1 回クリックするだけでデプロイできる、統合された無料のホステッド モッキング サービスを提供します。モックを有効にすると、すぐに統合 API コンソールで try-it が有効になり、RAML ファイルに挿入された baseURI を使用してモック API をさらに実行できます。
さらに、近い将来 (Node を含む) 追加のサーバー フレームワーク (Mule および JAX-RS フレームワークを既に持っています) をオープン ソース化する予定です。クライアントの生成はもう少し先ですが、間もなく登場します (javascript が最初、次にその他)。
開示: 私は RAML イニシアチブに深く関わっており、MuleSoft で開発した RAML ツールの多くのプロダクト マネージャーとして働いています。
RAML コンソールが十分に軽量でない場合は、https://github.com/kevinrenskers/raml2htmlが非常に便利で使い始めるのが簡単であることに気付くかもしれません。
RAML コンソールが実行するすべての機能 (そこから API をテストするための [試用] など) が含まれているわけではありませんが、それでも優れたドキュメント ツールです。