Swaggerの紹介
Swaggerは確かに良いことです。特にRestfulスタイルのプロジェクトでは、ビジネスコードに基づいてAPIインターフェイスドキュメントを自動的に生成できます。開発者は、RESTAP APIを具体的に維持する必要はほとんどありません。このフレームワークは、ビジネスコードのRestFutスタイルのAPIを自動的に生成でき、JSON形式で応答を自動的に表示するための対応するテストインターフェイスも提供します。バックエンド開発者とフロントエンドの間のコミュニケーションと調整コストを大幅に促進します。
Springfox-Swaggerの紹介
Swaggerの強力な機能により、Javaのオープンソース業界の大きなSpringフレームワークはすぐに維持されました。独自の利点を完全に利用し、Swaggerを独自のプロジェクトに統合し、Spring-Swaggerを統合しました。 Springfox自体は、独自のAOP特性のみを使用し、Swaggerをプラグに統合します。独自の世代のビジネスAPIは、それを達成するためにまだSwaggerに依存しています。
このフレームワークに関する情報は比較的少なく、それらのほとんどはエントリーレベルの簡単な使用です。このフレームワークを自分のプロジェクトに統合する過程で、多くの落とし穴に遭遇しました。これらの落とし穴を解決するために、私はそれが何であるかを見るためにそのソースコードを掘り下げなければなりませんでした。この記事では、Springfoxについての私の理解と、Springfoxの使用中に注意する必要があるものについて説明します。
スプリングフォックスの一般原則
Springfoxの一般的な原則は、プロジェクトの起動のプロセスで、Springコンテキストの初期化プロセス中に、フレームワークが構成に応じていくつかのSwagger関連の豆を現在のコンテキストに自動的にロードし、システム内でAPIドキュメントを生成する必要があるクラスを自動的にスキャンし、対応する情報キャッシュを生成することです。プロジェクトのMVC制御レイヤーがSpringMVCを使用する場合、これらのコントローラークラスのメソッドに従って、すべてのコントローラークラスを自動的にスキャンして対応するAPIドキュメントを生成します。
私のプロジェクトはSpringMVCであるため、この記事では、Springfoxの使用と原則を議論する例として、SRPING MVC統合Springfoxを使用しています。
SpringMVCをSpringfoxに統合する手順
まず、プロジェクトは次の3つの依存関係を追加する必要があります。
<！ - sring mvc依存関係 - > <依存関係> groupid> org.springframework </groupid> <artifactid> spring-webmvc </artifactid> <バージョン> 4.2.8.release> </dependency> <！ - swagger2コア依存関係 - > <依存関係> <グループ。 <artifactid> springfox-swagger2 </artifactid> <バージョン> 2.6.1 </version> </dependency> <！ - swagger-uiはプロジェクトのAPIディスプレイとテストインターフェイスを提供します - > <依存関係> <groupid> io.springfox </groupid> <artifactid> springfox-swox-swox-swox-swox-swox-artifactid> </</<
上記の3つの依存関係は、プロジェクト統合SpringMVCおよびSpringfoxの最も基本的な依存関係であり、他の依存関係はここで省略されています。 1つ目はSpringMVCの基本的な依存関係、2つ目はSwagger依存関係、3つ目はインターフェイス関連の依存関係です。これは必要ありません。 Springfoxに付属のAPIインターフェイスを使用したくない場合は、これを使用したり、プロジェクトに合ったインターフェイスのセットを書くこともできません。これらの依存関係を追加した後、システムはSpringfoxとSwaggerに関連するJARパッケージを自動的に追加します。私は少し見て、主に次のことがあることがわかりました。
Springfox-swagger2-2.6.1.jar
Swagger-Annotations-1.5.10.jar
Swagger-Models-1.5.10.jar
Springfox-spi-2.6.1.jar
Springfox-Core-2.6.1.jar
Springfox-schema-2.6.1.jar
Springfox-Swagger-Common-2.6.1.jar
Springfox-spring-web-2.6.1.jar
Guava-17.0.jar
Spring-Plugin-Core-1.2.0.Release.jar
Sprug-Plug-Metadata-1.2.0.Release.jar
spring-swagger-ui-2.6.1.jar
Jackson-Databind-2.2.3.Jar
Jackson-Annotations-2.2.3.jar
上記は、Springfoxが必要とするかもしれないと視覚的に考えている瓶であり、Springfoxが必要とするすべての瓶を完全に示していないかもしれません。上記の瓶から、Swaggerに依存することに加えて、PringfoxにはGuava、Spring-Plug、Jackson、その他の依存関係が必要であることがわかります（JacksonはJSONを生成するために必要な瓶パッケージです。
Springfoxの簡単な使用
Springfoxのデフォルト構成のみを使用する場合、SpringMVCとの統合は非常に簡単です。次のコードに似たクラスを書いて、プロジェクトに入れてください。コードは次のとおりです。
@configuration@enablewebmvc@enableswagger2publicclass apiconfig {}上記は空のJavaクラスファイルであることに注意してください。クラス名は自由に指定できますが、上記のクラスの@configuration、 @enablewebmvc、および @enableswagger2とマークされた3つの注釈を追加する必要があります。これにより、SpringMVCとSpringfoxの基本的な統合が完了します。プロジェクトが開始された後、3つの注釈を使用すると、次のアドレスを直接使用して、APIリストを表示できます。http：//127.0.0.1:8080/jaddemo/swagger-ui.html
これは確かに非常に魔法の効果です。 3つの簡単な注釈を使用すると、システムはプロジェクト内のすべてのコントローラークラスのすべてのAPIを自動的に表示します。次に、この構成クラスから始めて、その原則を単に分析しましょう。このクラスにはコードはありません。3つの注釈が重要な役割を果たすことは明らかです。その中で、@configurationアノテーションは、Springフレームワークで既に利用可能です。これは、@Component Meta Annotationによって識別される注釈です。したがって、この注釈を使用すると、Springはクラスを自動的に豆にインスタンス化し、スプリングコンテキストに登録します。したがって、2番目のannotation @enablewebmvcは、srpingmvcが有効になっていることを意味します。 Eclipseでこの注釈をクリックして、簡単に見てください。メタアノテーション@import（DelegatingWebMVCConFiguration.class）を介して、タイプの委任を象徴するwebmvcconfigurationの豆を春のコンテキストに詰めることです。このクラスの目的は、SpringMVC構成をSwaggerに提供することだと思います。 3番目の注釈： @enableSwagger2。名前を考えることができます。 Swagger 2を統合するために使用されます。メタアノテーションを介して：@import（{swagger2documentationconfiguration.class}）、swagger2documentationconfigurationタイプ構成Beanを導入しました。これはSwaggerのコア構成です。その中のコードは次のとおりです。
@configuration@import（{springfoxwebmvcconfiguration.class、swaggercommonconfiguration.class}）@componentscan（basepackages = {"springfox.documentation.swagher2.readers.parameter"、 "springfox.documentation.swagher2.weagher2"、 "springfox.documentation.swagger2.mappers"}）publicclassswagger2documentationconfiguration {@bean public jacksonmoduleregistrar swagger2module（）{returnnewswagger2jacksonmodule（）; }}このクラスヘッダーはいくつかの注釈を使用し、Springfoxwebmvcconfigurationクラスとswaggercommonconfigurationクラスを導入し、コンポーネントの注釈を介してSpringfox .swagger2関連の豆をスプリングコンテキストに自動的にスキャンします。ここで、私が最も興味を持っているのは、Springfoxwebmvcconfigurationクラスです。このクラスは、Springfox Integrated MVCのよりコア構成であるべきだと思います。クリックして、次のコードを表示します。
@configuration@import（{modelsconfiguration.class}）@componentscan（basepackages = { 「springfox.documentation.spring.web.scanners "、" springfox.documentation.spring.web.readers.operation "、" springfox.documentation.spring.web.readers.operation "、 "springfox.documentation.spring.parameter"、 "springfox.documentation.spring.web.plugins"、 "springfox.documentation.spring.web.paths"}）@enablePluginRegistries（{ documentationPlugin.class、apilistingBuilderPlugin.Class、OperationBuilderPlugin.Class、ParameterBuilderPlugin.Class、ResourceGroupingStrategy.Class、OperationModelsProviderPlugin、DefaultSprobiderPlugin.Class pathdecorator.class}）publicclassspringfoxwebmvcconfiguration {}このクラスの次のコードは、@Beanアノテーションを通じていくつかの新しい豆を追加することにすぎません。私はそれにあまり興味がありません。私が最も興味を持っているのは、@enablepluginregistriesを通して頭に追加されたものです。 Springfoxは、Swaggerを統合するためのスプリングプラグメカニズムに基づいています。スプリングプラグはどのように実装されますか？春プラグの原則をまだ研究する時間はありません。しかし、以下では、Swaggerの機能を拡張するためにプラグプラグインを書いていることに言及します。 @EnablePlugInRegistriesを介して上記のプラグはまだ利用できません。私が見たコードには、主にApilistingBuilderPlugin.Class、OperationBuilderPlugin.Class、ParameterBuilderPlugin.Class、ExpandedParameterBuilderPlugin.Class、ExpandedParametarBuilderPlugin.class、apilistingbuilderplugin.classが含まれます。
最初のApilistingBuilderPluginは、2つの実装クラス、つまりApilistingReaderとSwaggerApilistingReaderを備えています。その中で、ApilistingReaderはコントローラータイプに応じてAPIリストを自動的に生成し、SwaggerApilistingReaderは@APIアノテーションによって識別されたクラスに従ってAPIリストを生成します。 OperationBuilderPluginプラグインは、特定のAPIドキュメントを生成するために使用されます。このタイプのプラグインには、多くの実装クラスがあります。彼らはそれぞれ分裂し、自分のことをします。詳細は注意深く見ていませんでしたが、実装クラスの1つであるOperationParameterReaderにのみ焦点を当てました。このクラスは、APIパラメーターの読み取りに使用されるプラグインです。 ModelAttributeParameterexpanderツールクラスに依存しています。これは、コントローラー内のインターフェイスメソッドパラメーターの非シンプルタイプのコマンドオブジェクトを自動的に解析して、すべての属性を含むパラメーターリストを取得できます（以下に導入された無限の再帰を引き起こすピットがあります）。 ExpandedParametarBuilderPluginプラグインは、主に、このパラメーターのデータ型を決定するなど、インターフェイスパラメーターの関数を拡張するために使用されます。このインターフェイスの必要なパラメーターなど。システムが起動すると、それらは調整され、一部はインターフェイスリストをスキャンするために使用され、一部はインターフェイスパラメーターなどを読み取るために使用されます。それらの一般的な目的は、システム内のすべてのAPIインターフェイスをスキャンして、ユーザーが表示できるようにキャッシュすることです。それでは、この一連のテーブルプラグはどのように調整されており、その実行入り口はどこにありますか？
上記のSpringfoxwebmvcconfigurationクラスのコードヘッダーにあるコンポーネントの注釈コンテンツに注意点を掲載します。この注釈では、springfox.documentation.spring.web.pluginsと呼ばれるパッケージがスキャンされます。このパッケージは、Springfox-Spring-Web-2.6.1.jarにあります。このパッケージの下には、2つの非常にコアクラス、つまりDocumentationPluginsManagerとDocumentationPluginsBootStrapperがあることがわかりました。最初のDocumentationPluginsManagerでは、インターフェイスを実装していないBeanですが、プラグインリレジストリタイプの多くのプロパティがあり、それらはすべて@Autowired Annotationを通じてプロパティ値に注入されます。クラス名を組み合わせることで、これがすべてのプラグを管理するマネージャーであると考えるのは簡単です。コンポーネントの構成があるため、アノテーションの構成のため、すべてのプラグインスタンスが春までに豆にインスタンスされ、このDocumentationPluginsManagerインスタンスに注入され、均一に管理されます。このパッケージDocumentationPluginsBootStrapperのもう1つの重要なクラスでは、名前を見るとプラグの起動クラスかもしれません。クリックして詳細を調べると、実際に@Componentによって識別されたコンポーネントであり、その構成方法がドキュメントPluginsManagerインスタンスを注入することがわかります。最も重要なことは、SmartLifeCycleインターフェイスも実装することです。スプリングビーンズのライフサイクルを知っている人なら誰でも、このコンポーネントが豆にインスタンス化され、SRPINGコンテキストで管理されると、そのstart（）メソッドが自動的に呼び出されることを知っています。 start（）をクリックすると、コードを確認すると、コードScandocumentation（buildcontext（blusk））があることがわかります。 APIドキュメントをスキャンするために使用されます。このメソッドのコードをさらに追跡することで、このメソッドは最終的にそのDocumentationPluginsManagerプロパティを使用して、すべてのプラグを調整してシステム全体をスキャンし、APIドキュメントを生成することがわかります。スキャン結果は、DocumentcationCacheクラスのマッププロパティでキャッシュされます。
上記は、Springfoxを統合するSRPINGMVCの一般原則です。主に、enableSwagger2アノテーションを介して一連の豆をSRPINGコンテキストに注入し、システムが起動するときにシステムのコントローラークラスを自動的にスキャンし、対応するAPI情報を生成し、キャッシュします。さらに、@Controller Annotationによって識別されたいくつかのコントローラークラスに、UIモジュールがAPIリストにアクセスするためのエントリとして識別されます。たとえば、Springfox-Swagger2-2.6.1.jarパッケージのSwagger2Controllerクラス。このコントローラーは、APIリストにアクセスするためにUIモジュールで使用されるインターフェイスアドレスです。アドレスにアクセスするhttp://127.0.0.1:8080/jaddemo/swagher-ui.htmlは、APIリストを表示するために、ブラウザを介して、API情報（JSON形式）を非同期に取得していることがわかります。 http://127.0.0.1:8080/jaddemo/v2/api-docs？group = sysysgroupとインターフェイスに表示します。このアドレスの背景に対応するコントローラーエントリは、上記のSwagger2Controllerクラスです。リクエストを受信した後、このクラスは、事前に初期化されたキャッシュからAPI情報を直接取得して、JSON文字列リターンを生成します。
Springfoxの原則を理解した後、Springfoxの使用中に遭遇した落とし穴を見てみましょう。
Springfoxの最初の大きなピット：構成クラスによって生成されたBeanは、Spring MVCと同じコンテキストを共有する必要があります。
上記のように、SpringMVCプロジェクトでは、Springfoxの統合は、プロジェクトのビジネスコードなしで次のように単純な構成クラスを記述するためだけです。
@configuration@enablewebmvc@enableswagger2publicclass apiconfig {}@Configuration Annotationのため、Springは自動的に豆にインスタンス化され、コンテキストに注入します。しかし、注目すべき落とし穴の1つは、この豆がスプリングMVCと同じコンテキストにある必要があるというコンテキストです。理解する方法は？実際のSpring MVCプロジェクトでは、通常2つのコンテキストがあり、1つはコンテキストに続くコンテキストがあり、もう1つはSpring MVCです（これはコンテキストに従うサブコンテキストです）。コンテキストは、web.xmlファイルのspringに関連するorg.springframework.web.context.request.requestContextListenerリスナーです。ロードされたコンテキストは通常、Spring-Contet.xmlという構成ファイルとして記述されます。ここの豆は最終的にコンテキストに初期化されます。主に、システム内のサービス、DAO、およびその他の豆、およびデータソース、物などが含まれます。別のコンテキストは、Web.xmlのスプリングMVCに関連するorg.springframework.web.servlet.dispatcherservletを介してロードされるスプリングMVCです。通常、Spring-Mvc.xmlという構成ファイルがあります。 Apiconfigクラスを書くときは、@Configurationアノテーションでロードすることにした場合、このクラスのパスがSpringMVCのコンポーネントスキャン構成の基本パッケージ範囲内にあることを確認する必要があります。 Apiconfigが春にロードされると、一連の豆が注入されるためです。これらの豆では、すべてのコントローラークラスを自動的にスキャンするために、一部の豆はSpringMVCの一部の豆に依存する必要があります。プロジェクトが、コンテキストのサブコンテキストとしてSRPingMVCのコンテキストをコンテキストから分離した場合。誤ってこのapiconfigタイプのBeanを以前のテキストでロードする場合、ルートコンテキストにスプリングMVCコンテキストに構成クラスがないためです。
実際、SwaggerのAPI機能は生産プロジェクトではオプションだと思うので、@Configuration Annotationを介してSwaggerの構成に同意しません。私たちのSwaggerは、プロジェクトのフロントエンドチーム開発の環境をテストするために、または他のシステムがインターフェイスを統合するために環境をテストするためによく使用されます。システムがオンラインになると、これらのAPIリストが生産システムに隠される可能性があります。ただし、構成が@Configurationアノテーションを介してJavaコードに記述されている場合、オンラインになったときにこの関数を削除する場合、恥ずかしくなり、Javaコードを変更して再コンパイルする必要があります。これに基づいて、Springで最も従来のXMLファイルを構成する方法をお勧めします。特定の方法は、@Configurationアノテーションを削除し、スプリングXML構成ファイルに<Bean/>と同様のBean構成を書き込みます。ルートコンテキストがMVCコンテキストから分離されているプロジェクトでは、Spring-MVC.xmlに直接構成され、SpringMVCコンテキストと同じコンテキストである必要があることが保証されます。
Springfoxの2番目に大きなピット：コントローラークラスのパラメーターは、無限の再帰を防ぐために注意してください。
Spring MVCには、強力なパラメーター結合メカニズムがあり、リクエストパラメーターを自動的にカスタムコマンドオブジェクトにバインドできます。したがって、怠け者になるために、多くの開発者は、コントローラーを作成するときに、コントローラーメソッドのパラメーターとしてエンティティオブジェクトを直接使用します。たとえば、次の例コード：
@RequestMapping（value = "update"）public string update（menuvomenuvo、Model Model）{}これは、ほとんどのプログラマーがエンティティを変更するためにコントローラーで書きたいコードです。 Swaggerと統合するとき、ここには大きなピットがあります。メニューボのすべてのプロパティが基本タイプである場合、それは問題ありません、何も問題がありません。ただし、このクラスに他のカスタムタイプの属性があり、この属性が直接的または間接的に独自のタイプの属性が存在する場合、問題があります。たとえば、メニューボクラスがメニュークラスの場合、親メニューを表すメニューボタイプのプロパティの親も含まれています。このようにして、Swaggerモジュールは、APIをロードできないためにシステムが起動するときにエラーを直接報告します。エラーの理由は、この方法をロードするときに、更新方法のパラメーターが解析されるためです。パラメーターMenuvoが単純なタイプではない場合、すべてのクラス属性は自動的に再帰的に解釈されます。これにより、無限の再帰の死んだループに簡単に落ちることができます。
この問題を解決するために、OperationParameterReaderプラグインの実装クラスと依存するModelAttributeParameterexpanderツールクラスを作成しました。構成を介してSrpingFoxの元の2つのクラスを置き換え、パラメーター分析を列のように解析するロジックを置き換え、無限の再帰を回避します。もちろん、これはソースコードレベルを変更する方法と同等です。私はこの問題に対するより完璧な解決策をまだ見つけていないので、Spring-Fox Swaggerを使用するときに、この無限の再帰を避けようとすることをお勧めします。結局のところ、これはSpringMVCコマンドオブジェクトの仕様に準拠していません。 SpringMVCパラメーターを持つコマンドオブジェクトは、簡単な基本型属性のみであることが好ましいです。
Springfoxの3番目のメジャーピット：APIグループ化関連、ドケットインスタンスは潜在的にロードできません
Springfoxは、すべてのAPIをデフォルトでグループに分割します。 http://127.0.0.1:8080/jaddemo/swagger-ui.htmlに似たアドレスからアクセスすると、すべてのAPIリストが同じページにロードされます。このようにして、システムが少し大きく、APIがもう少し大きい場合、ページは偽造されるため、APIをグループ化することが非常に必要です。 APIグループは、APICONF構成ファイルの@Beanアノテーションによって定義されます。インターネット上の一般的な構成は次のとおりです。
@enableWebmvc@enableSwagger2publicclass apiconfig {@bean public docket customdocket（）{return newdocket（documentationtype.swagher_2）.apiinfo（apiinfo（））; }}上記のコードでは、@Beanからドケットが注入されます。この構成は必要ありません。この構成が使用できない場合、フレームワークはそれ自体でデフォルトのドケットインスタンスを生成します。このドケットインスタンスの目的は、APIバージョン、著者などの基本情報など、管理できるすべてのAPIの公開情報を指定し、どのAPIがリストされているかを指定することです（APIアドレスまたは注釈でフィルタリングされます）。
次のコードなど、複数のドケットインスタンスがあります。
@enablewebmvc@enableSwagger2publicclass apiconfig {@bean public docket customdocket1（）{return newdocket（documentationtype.swagher_2）.groupName（ "apigroup1"）。apiinfo（apiinfo（））。 } @bean public Docket customdocket2（）{return newdocket（documentationtype.swagger_2）.groupName（ "apigroup2"）。apiinfo（apiinfo（））。 }}プロジェクトで複数のドケットインスタンスが構成されている場合、APIをグループ化できます。たとえば、上記のコードはAPIを2つのグループに分割します。この場合、各グループには、上記のコードに「APIGROUP1」や「APIGROUP2」などの異なる名前を割り当てる必要があります。各グループはパスを使用して、どのグループを指定して、ANTスタイルのアドレス式を介してどのAPIを管理できます。たとえば、上記の構成では、管理アドレスの最初のグループは、 /sys /の開始のAPIです。 /shop /の開始との管理APIの2番目のグループ。もちろん、クラスアノテーション、メソッドアノテーション、正規表現に対処するなど、他にも多くのフィルタリング方法があります。グループ化後、APIリストインターフェイスの右上隅にあるドロップダウンオプションで異なるAPIグループを選択できます。これにより、プロジェクトのAPIリストが異なるページに分散します。これにより、ページがあまりにも多くのAPIをロードする必要があるため、死んでいるふりをすることなく管理を促進します。
ただし、@Configurationを使用するように、@Beanを使用してAPIをグループ化するためにドケットインスタンスを構成することに同意しません。このため、コードは死に至ります。したがって、これらの同様の機能を実装するために、XMLファイルに独自のドケットインスタンスを構成することをお勧めします。もちろん、ドケット内の多くの属性を考慮すると、豆を直接構成する方が面倒です。ドケット用の工場出荷時代を自分で書いてから、XMLファイルでFactoryBeanを構成できます。ただし、ドケットをXMLに設定する場合。別の大きなピットに遭遇します。つまり、豆のスプリングの荷重方法はデフォルトで怠zyになります。これらのドケットインスタンスをXMLで直接構成した後。効果がなく、ページの左上隅にドロップダウンリストにグループ化アイテムがないことがわかります。
この問題は数時間私を悩ませてきました。その後、経験に基づいて、スプリングビーンがデフォルトで怠zyなロードであり、このドケットインスタンスがスプリングのコンテキストにロードされていないためである可能性があると推測されました。結局のところ、私の推測は正しいです。これがSpringfoxのバグなのか、それともドケット構成を元のJavaコードからXML構成ファイルに移動すべきではないのかどうかはわかりません。
Springfoxの他の落とし穴： Springfoxには他にもいくつかの落とし穴があります。たとえば、@Apioperationアノテーションでは、httpmethod属性が特定のgetまたはpostメソッドとして指定されていない場合、get、post、削除、putなどのすべてのメソッドがAPIリストにリストされるため、APIリストが重複しすぎています。さらに、テスト中に、ログイン許可の問題などに遭遇しました。これらの小さなピットの山は、スペースが限られているため、あまり言いません。 @API、@Apioperation、@Apiparamなどの注釈の使用もあります。このオンラインで多くのドキュメントを繰り返すことはありません。
上記はこの記事のすべての内容です。みんなの学習に役立つことを願っています。誰もがwulin.comをもっとサポートすることを願っています。