Fosrestbundle: ルートからのRESTAPIドキュメントの生成

いくつかのインスピレーションについては、http： //getfrapi.com/スクリーンキャストを確認してください。

私はすでにそれを見ました。 しかし、私は彼らの実現において多くのものが好きではありません。 まず第一に、彼らのRESTはRESTfulではありません:-D

「インスピレーション」と私は彼らの残りについて話していませんでしたが、彼らのドキュメント（およびテスト）世代について話していました:)

個人的には気に入らないのですが、WADL形式のドキュメントの生成について話し合うことはできますか？

http://www.w3.org/Submission/wadl/

生成よりも優れた方向性は、ドキュメントコントローラー/ビューの迅速な構築を可能にするビューヘルパーを提供することであるのではないかと思います。 これは、単に構造を生成するよりも優れているようであり、より拡張可能/保守可能です。 言い換えれば、APIドキュメントの生成はFRAPIのユースケース（アプリにドロップ）にはうまく機能すると思いますが、この機能が「そのまま」必要かどうか、またはそれが理にかなっているのかどうか疑問に思います。

クライアント向けのドキュメントについて話しているのですか？

念頭に置いておいてください、それはRESTが避けようとしていることです:)

odino：確かに。 しかし、HATEAOSに従っている場合でも、ヘッダーを検査する必要があるという事実のようなものがあります。 また、さまざまなステータスコードを期待することを知っておく必要がありますが、どのステータスコードが「より可能性が高い」かを知ることは依然として良いことです。 APIのカジュアルなレビューに最適です。

また、無視すべきもう1つのトピック：木を殺すのが好きなクライアントもいます。この紙のページを埋めるのに多くの時間を無駄にする必要がないのは素晴らしいことです:)

同意します。避けるべき唯一のことは、生成されたドキュメントに大きく依存することです。そうしないと、WSDLを複製します。

ツリーキラーのために親指を立てる:)

私の知る限り、真のREST APIドキュメントは、URLではなく、メディアタイプとその関係の定義に関するものです。 例： http ：//kenai.com/projects/suncloudapis/pages/Home、http： //amundsen.com/media-types/collection/

ただし、単純なHTTP APIの場合、これはWebプロジェクトの80％に当てはまりますが、この機能は引き続き役立ちます。

はい、vladar、URIテンプレートは明らかに悪です。 ただし、RESTバンドルを開発する必要がある場合は、それらの原則に従う必要があります。

URIテンプレートはApiBundleに適しています

http://swagger.wordnik.com/から概念を取り入れることができるかもしれません

：+1：Swaggerに。 これはすごいですね！

同様のエクスペリエンスを作成するために、次のことができる場合があります。

• @apidocなどのマークが付いた解析メソッド
• @apidocマークされたメソッドのdocblockからメソッドとパラメーターの説明を取得します
• アクションごとにコールのインラインテストを許可します。

全体として、Swaggerのような画面を実現することはかなり実行可能であり、このバンドルにとって非常に理にかなっていると思います。

もう1つのオプションは、Swaggerが消費するJSONを生成することですが、それにはある程度の重みがあります（Java）...むしろ「類似した」実装を見たいと思います。

互換性のあるJSONを生成することが私の最初の考えでした。 私は週末にもう少し深く掘り下げます、多分いくつかの速い'n汚いプロトタイピングが可能であるかもしれません。

@pminnieurは、統合するのではなく、同じ基本機能を同じように簡単に提供できるようです。

少なくとも、 https：//github.com/FriendsOfSymfony/FOSJsRoutingBundleのように機能する可能性があります。つまり、派手なHTML / CSSを追加し、ある種のAPIドキュメントを使用してRESTfulルートを公開するだけです。 たぶん、より多くの情報をサポートするためにいくつかの注釈を使用することができます。

これから始めたいのですが、コードを専用のバンドル（FOSRestAPIExplorerBundleなど）に入れる方がよいと思います。 質問は、Swagger APIのみをサポートするのか（SwaggerはJSONで収集および公開される情報を視覚化するために使用されるので）、独自のWebインターフェイスも提供するのでしょうか？

別のバンドルは良い考えのように聞こえます。 Swaggerのみをサポートする場合は、バンドル名でそのように言いたい場合があります。 他の何かもサポートしたいかどうかはわかりません。 あなたのモチベーションと闊歩の質に依存します。 闊歩についての1つの質問：外部サービスに公開したくない内部APIとどのように連携しますか？

Swagger JSONを公開したくない場合は、URLを公開しないようにする必要があると思います...：D真剣に、アノテーションを使用したいのですが、ルートを公開したくない場合はpublic、 @Expose()アノテーションを追加したり、 @Expose(false)を追加したりすることはありません-このようなものです。 FOSJsRoutingBundleがそれを処理する方法を構成できるのと同じように（デフォルトですべてを公開するか、ホワイトリストを公開します）。 「これがパブリックAPIのリンクであり、このリンクはあなただけのものです」という意味の場合、セキュリティコンポーネントを含む@Api("public")や@Api("private")のようなアノテーションを追加して、別のAPIを配布できるようにする場合があります。さまざまな人へのドキュメント（およびそれらへのアクセスを制御します）。

名前について：一般的な名前が欲しいのですが、Swaggerはサポートされる最初のAPIドキュメントサービスになります。 他のサービスを追加したい場合は、それを行うことができます（最初から始めてはいけません）。 たとえば、 @odinoはWADLサポートを追加できます。 少なくとも私もWebインターフェースを提供したいと思います。

始める前にアイデアや問題を収集するために、これまでにGitHubリポジトリを作成しました。 議論する質問やトピックについては、自由に問題を開いてください（名前付けも確かに議論される可能性があります）;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

いいよ。 物事が形になったら..それをFOSに移すことができます

https://github.com/wordnik/swagger-uiを「ディスプレイ」として利用することを計画していますか？

そもそもそうです swagger-uiで使用されるswagger-spec準拠のjsonのみを生成します。

https://github.com/nelmio/NelmioApiDocBundleを支持して終了

私はこれが非常に古いことを知っていますが、それ以来いくつかのことが変更され、Swagger/Openapiのパッケージ/バンドルを探しているときにこれを比較的早く見つけました。
これを再考する機会はありますか？ NelmioApiDocBundleが放棄され、Symfony for Swagger / OpenApi（または他の実際のRAML、...？）に統合される実際の代替手段が見当たらないためです。