web-dev-qa-db-ja.com

Swagger API宣言からJSONスキーマを生成する方法

Swagger v 1.2 を使用したサービスのSwagger API宣言があります

Swaggerに対する私の最初の感覚は、JSONスキーマ（ドラフト3および最近のドラフト4）に非常に近く、リクエストおよび応答オブジェクトのJSONスキーマを比較的簡単に生成できるということでした。

ただし、Swaggerの一部はJSONスキーマ構造を再利用しますが、機能のサブセットのみを使用し、Modelsに独自の継承を導入します（subTypesおよびdiscriminatorを使用）。

質問：Swagger API宣言から使用可能なJSONスキーマを生成できる既存のプロジェクトまたはコードがありますか？

最適なJSONスキーマドラフト4およびPythonの使用（ただし、何かあれば喜んで見つけます）。

swaggerjsonschema
66
Jan Vlcinsky

REST AP​​Iを指定し、関連するテストスイートで再利用するためにSwaggerを使用して長い戦いをした後、自分の経験を共有します（自分の質問に答えます）。

SwaggerはJSON Schema Draft 4のサブセットのみをサポートします

Swagger 1.2および2.0状態の仕様は、JSON Schema Draft 4のサブセットのみをサポートします（s。 here ）。この意味は：

  • 有効な各JSONスキーマがSwaggerによって完全にサポートされていることを信頼することはできません。
  • xMLを考えると、SwaggerはJSON Schema Draft 4によって提供されるJSON構造のサブセットの正規表現のみをサポートします。

言い換えると：

  • Swagger（1.2および2.0）は、JSON Schema Draft 4の観点から有効な多くのJSON構造の使用をサポートしていません（Draft 3にも同じことが当てはまります）。
  • Swaggerは一般的なXMLデータ構造をサポートしていません。非常に制限された構造のみが許可されています。

実際には、JSONまたはXMLでデータを設計することから始めることはできません。Swaggerでは、Swaggerで開始および終了する必要があります。

JSONスキーマの取得は理論的には可能ですが、簡単ではありません

私は、Swagger API仕様を取得し、JSONスキーマドラフト4を作成するライブラリのコーディングにしばらく時間を費やしました。

  • 簡単ではなかった
  • jSONスキーマが提供するもののサブセットのみを使用できるという失望した発見を得ました。すでにいくつかのJSONペイロードが提案されており、Swagger仕様フレームワークで許可されているものに合わせて修正を開始する必要がありました。

APIを表示およびテストするための本当に見栄えの良いUIを除いて（はい、誰もが同意し、視覚的に非常に楽しいです）、仕様フレームワークが私たちが望むものを使用することを許可していないが、予期しない制限を追加することは奇妙であることがわかりました私たちの設計に。

JSONまたはXMLスキーマの完全なサポートが必要な場合は、RAMLを使用してください

他のAPI仕様フレームワークを調査して、RAMLを見つけました。 JSON Schema Draft 3/4またはW3C XML Schema 1.0のデータ構造をサポートすることにより一から構築されているため、エクスペリエンスは素晴らしかった-ペイロードの構造が設計されており、API仕様を非常に迅速にオーサリングし、実際のリクエストの検証ができたスキーマは制限を加えることなく仕様の重要なコンポーネントであるため、定義されたスキーマに対する応答は非常に簡単でした。

RAMLはその時点でバージョン0.8でした（バージョン1.0はまだリリースされていませんでした）。

質問を修正すると、実際の解決策につながります

良い質問が解決策の半分になります。私の本当の期待を満たせなかったので、私の質問は間違っていました。修正された質問は次のとおりです。

任意のJSON Schema Draft 4またはW3C XML Schema 1.0で定義されたペイロードを使用してREST AP​​Iを指定するために使用する仕様フレームワークおよび手法。

このような質問に対する私の答えは次のとおりです。

  1. JSON Schema Draft 4またはW3C XML Schemaでペイロードを設計します
  2. RAMLを使用してREST AP​​Iを記述します（現時点ではv0.8）。

使用可能な他の仕様フレームワークがあるかもしれませんが、Swagger（v1.2とv2.0のどちらでもない）は間違いなくそうではありません。本当に多くの機能（コード生成、APIの見栄えの良いドキュメントなど）を提供する以外に、上記の更新された質問に対するソリューションの提供に失敗します。

72
Jan Vlcinsky

openapi2jsonschema という名前で同じことを行うpythonツールがあります。 pipを使用して簡単にインストールできます。

Openapi2のreadmeは、それを使用する最も簡単な方法を示しています。

openapi2jsonschema https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json

お役に立てれば。

6
Akash Masand

ツールを作成しました pyswagger ニーズに合っているようです。

Swagger API宣言をロードし、pythonオブジェクトとSwaggerプリミティブを相互に変換できます。 Swagger対応へのリクエストを行うことができるクライアント実装のセット（requestsおよびtornado.httpclient.AsyncHTTPClientを含む）も提供します直接サービス。

このツールは、PythonでSwaggerを適応させるときに遭遇した最初の問題を解決する傾向があり、現在でもかなり新しいものです。提案を歓迎します。

5
mission.liao

Swaggerを発見し、これが要件になるのと同じことを自問しました。

この答えを見つけました

ここから直接お試しください：

http://petstore.swagger.wordnik.com/

そして、これをあなたのURLとして入れてください：

http://petstore.swagger.wordnik.com/api/api-docs/pet

すべてのモデルが表示されます。しませんか？それとも何か不足していますか？

ユーザーグループ内： https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

問題は、「モデル」が有効なJSONスキーマ4.0/JSONハイパースキーマを指すかどうかです

2
sebilasse

私はこのようにそれをすることでいくらか成功しました：

swagger.yaml-> proto-> jsonschema

openapi2proto を使用してSwagger yamlからprotoファイルを生成し、次に protoc-gen-jsonschema を使用してJSONSchemaを生成しました。型指定されたJSONSchemaを取得するのに十分ですが、proto3は「必須」型をサポートしていないため、これをお見逃しなく。

1
Chrusty