問題タブ [swagger-ui]

ここ数日、API ブループリント、RAML、または Swagger を使用する必要があるかどうかを理解しようと努めてきました。

swagger には最大のコミュニティがあるように見えますが、よく見るとドキュメンテーションが大幅に不足しているように感じます (コードを何度も見て、現在のプロジェクトに統合することを余儀なくされました)、多くの github の問題とスタックオーバーフロー質問は未回答です。

ここで何かが足りない可能性はありますか? 私が欲しいのは、API ドキュメントを作成し、エンドポイントをテストするのに役立つツールだけです。

なぜ闊歩をサーバーロジックの一部にする必要があるのですか?? エディターでswaggerファイルを作成し、それらをUIに直接提供すると、壊れます..

私が知る限り、それはサーバーをわずかに遅くし、不器用に維持された多くの統合の存在を強制します:p ここで何が欠けていますか?

私が構築している web-api を記述するために Swagger を使用しようとしています。問題は、複雑な json オブジェクトを記述する方法を理解できないことですか?

たとえば、このオブジェクトを記述する方法は次のとおりです。

4.0.31 を使用すると、AppHost の Configure メソッドは次のように宣言されます。

これにより、swagger-ui の URL が ../api/resources の https バージョンに設定されるという印象を受けましたが、次のように、swagger URL テキストボックスで通常の http エンドポイントを引き続き取得しています。

当社の Web サーバーは、SSL オフロードを実行する (SSL を必要とする) ロードバランサーの背後にあるため、URL は次のようになります。

良い点として、「UseHttpsLinks」を使用すると、エンドポイント URL を修正すると、実際に swagger-ui が機能するようになります。それなしではまったく機能しませんでした！

開発、QA、およびステージング環境では、url プロパティが本番環境を指しているため、ハックとして仮想ファイル システムを介して代わりの index.html を使用して、swagger url プロパティをオーバーライドしています...(あまり良くありません)

私は、Jersey ベースの REST API を文書化するために swagger ツールを使用しています (私が使用している swaggerui は 2014 年 6 月にダウンロードされました。この問題が後のバージョンで修正されたかどうかはわかりませんが、そのコードに多くのカスタマイズを行ったので、もう一度カスタマイズするために多くの時間を費やすことなく、最新のものをダウンロードするオプションはありません)。

これまでのところ、すべての転送オブジェクトには 1 レベルの深さのプロパティがあります (pojo は埋め込まれていません)。しかし、より複雑なオブジェクト (2 レベルの深さ) を返すレスト パスをいくつか追加したところ、オブジェクトが埋め込まれている場合、SwaggerUI が JSON モデル スキーマを展開していないことがわかりました。

以下は、swagger doc の重要な部分です。

埋め込まれたオブジェクトは User と Address で、json 応答に示されているように、それらのモデルは正しく作成されています。

しかし、SwaggerUI を開くと、次の情報しか表示されません。

しかし、次のようなものが表示されるはずです。

内部プロパティを展開するコードに何か問題がある可能性があります。javascript コンソールにエラーが表示されないので、これはバグだと思います。

Swagger を使用して、jax-rs ベースの API のドキュメントを生成しています。私のモデルの1つには、次のプロパティがあります。

ただし、UI で生成される JSON モデルは次のとおりです。

したがって、明らかに XmlElementWrapper 注釈は解析されません。Swagger に要素を正しくネストさせるにはどうすればよいですか?

Spring Boot アプリケーション用の RESTful API があります。カスタムメディアタイプを追加しようとすることに関連する別の問題を理解しようとしていたときに、これに遭遇しました。

これを実行しようとした後HttpMediaTypeNotAcceptable、API ドキュメントを表示しようとすると例外が発生しました。この例外は、ログにのみ表示されます (レベルを に上げた場合DEBUG)。ブラウザに が表示されます406 undefined。スクリーンショットは次のとおりです。

Spring Boot のログから得られる例外は次のとおりです。

問題の根本は、既存の生産可能なメディア タイプが上書きされることです。

上記のコードがない場合、リストには次のものが含まれます。

• application/hal+json
• application/json;charset=UTF-8
• application/*+json;charset=UTF-8.

私の変更により、リストにはapplication/hal+json私のカスタム メディア タイプのみが含まれます。application/jsonしたがって、Swagger UIのAccept:ヘッダーにhttp://localhost:8080/api-docsベンドがあるため、Spring は互​​換性のあるメディア タイプをまったく見つけることができませんapplication/hal+json(curl を使用して確認しました)。

Swagger UI はおそらく accept ヘッダーを に設定するapplication/json,application/hal+jsonか、または のようなワイルドカードを使用する必要があると思いapplication/*+jsonます。

Javaでswaggerを使用しています。

コードの requestAttributes を介して callerId というヘッダーを読み取っています。注釈 @HeaderParam を介してヘッダーを使用していません。

このため、ヘッダー セクションは試行用の Swagger UI に表示されません。

このヘッダーを試用フォームに表示するにはどうすればよいですか。

ヘッダー値をハードコーディングせずにこれを達成する方法はありますか?

前もって感謝します。