Swagger 2.0は不純なREST APIデザインを有効にしますか？

Question

現在のSwagger仕様では、Swaggerをとして使用して、RESTful APIを記述して文書化しています。私は、これはむしろ私が闊歩は、単にいくつかの理由のためにHTTP APIを記述するために有用であると考える場合ではないと思う：

1. 闊歩仕様はPathとDefinitionような要素を持っていますが、彼らは明確にマッピングされませんREST data elementsは、リソース、表現、メディアの種類があります。 REST APIを効果的に記述するためには、APIのコンテキストで明示的なRESTデータ要素を定義する必要があります。
2. ハイパーリンクはSwagger仕様のファーストクラスのオブジェクトではないため、ハイパーリンクとその重要な記述属性であるリンク関係は簡単に削除することができます。実際、ハイパーリンクはまったく言及されていません。
3. HTTPパス彼の有名なblog postで作られたポイントフィールディングの明確な違反であると思われ、フロントとセンターにある：

REST APIは、固定されたリソース名や階層を定義してはなりません（

本質的に、Swagger 2.0仕様を使用して定義されたAPIは、RESTに違反するHATEOASに制約されないAPIを設計すると考えています。

これが正しいのですか、何か不足していますか？

Answer 1

私は一応同意します。 Swaggerは本当にREST準拠のAPIを定義するのには適していません。問題は、人々が多くの異なる方法でRESTを定義することです。リチャードソンの成熟度モデルは、これらの異なる定義を記述するのに役立ちます。

レベル0 REST APIは、すべてのリクエストを1つのURIと1つのHTTPメソッドでパイプします。このレベルには、HTTPを使用するすべてのAPIが含まれます。実際には、人々はこのRESTをめったに呼びませんが、それは起こります（おそらくマーケティング上の理由から）。

レベル1 REST APIは多くのURIを使用しますが、1つのHTTPメソッド（通常はPOST）のみを使用します。実際には、これはもはやRESTをめったに呼びませんでしたが、一般的な時がありました。

レベル2 REST APIは、リソースと統一インターフェイスの概念が導入されています。これらのAPIには、リソースを表すURIがあり、HTTPメソッドを使用してそれらのリソースに対してCRUD操作を実行します。実際には、人々はこれをRESTfulとしてレベル1と区別するように言い始めました。私はRESTのこの解釈を普及させるためにRuby on Railsを評価しますが、それを裏付けることはできません。いずれにしても、SwaggerがRESTful APIを記述すると主張している場合、レベル2は、を参照している定義です。

レベル3 REST APIは、RESTアーキテクチャスタイルに完全に準拠しています。特に、それらはHATEOASを使用することによって特徴付けられる。あなたの質問にあなたが配ったすべての懸念事項は、このレベルまで考慮されていません。実際には、これらのHypermedia APIを、レベル2の定義を参照するRESTfulの現在確立されている定義と区別するために呼び出す人々もいます。

私はRESTのご理解を闊歩によって使用されるものよりも多くの「成熟」であるため、あなただけ（私は経験から話す）、それを使用しようとしてイライラされると言うでしょう。 Hypermedia APIを定義する私の個人的な選択はJSON Hyper-Schemaです。それはSwaggerが持っているすばらしいツールのすべてに一致するわけではありませんが、レベル3でAPIを書くことができます。普及しているAPI定義言語で言えることはそれ以上です。