مقدمة إلى Swagger
Swagger هو في الواقع شيء جيد. يمكنه تلقائيًا إنشاء مستندات واجهة API استنادًا إلى رمز العمل ، وخاصة للمشاريع بأسلوب مريح. لا يمكن للمطورين بالكاد الحفاظ على واجهة برمجة تطبيقات Restap على وجه التحديد. يمكن لهذا الإطار تلقائيًا إنشاء واجهات برمجة التطبيقات على غرار RESTFUT لرمز عملك ، ويوفر أيضًا واجهة اختبار مقابلة لعرض الاستجابة تلقائيًا بتنسيق JSON. إنه يسهل بشكل كبير تكاليف الاتصال والتنسيق بين مطوري الواجهة الخلفية والواجهة الأمامية.
مقدمة إلى Springfox-Swagger
من خلال الوظائف القوية لـ Swagger ، سرعان ما حافظ إطار عمل Java Open Source Big Spring. استخدمت بالكامل مزاياها الخاصة ، وتكامل التباهي في مشروعها الخاص ، ودمجت لعبة Spring-Swagger ، والتي تطورت لاحقًا إلى Springfox. يستخدم Springfox نفسه خصائص AOP الخاصة به فقط ويدمج Swagger في القابس. لا يزال جيل واجهات برمجة تطبيقات الأعمال الخاصة به يعتمد على Swagger لتحقيق ذلك.
هناك معلومات قليلة نسبيًا حول هذا الإطار ، ومعظمها من الاستخدامات البسيطة للمبتدئين. واجهت العديد من المزالق في عملية دمج هذا الإطار في مشروعي. من أجل حل هذه المزالق ، اضطررت إلى إخراج رمز المصدر الخاص به لمعرفة ما كان عليه. تصف هذه المقالة فهمي لـ Springfox وما يجب إيلاء الاهتمام به أثناء استخدام Springfox.
المبدأ العام لـ Springfox
المبدأ العام لـ SpringFox هو أنه في عملية بدء تشغيل المشروع ، أثناء عملية تهيئة سياق Spring ، يقوم الإطار تلقائيًا بتحميل بعض الفاصوليا المتعلقة بالتبخيل في السياق الحالي وفقًا للتكوين ، ويفحص الفئات التي قد تحتاج تلقائيًا إلى إنشاء مستندات واجهة برمجة التطبيقات في النظام ، وتوليد خبش المعلومات المقابل تلقائيًا. إذا كانت طبقة التحكم MVC للمشروع تستخدم springMVC ، فستقوم تلقائيًا بمسح جميع فئات وحدة التحكم لإنشاء مستندات API المقابلة وفقًا للطرق في فئات التحكم هذه.
نظرًا لأن مشروعي هو springMVC ، فإن هذه المقالة تستخدم Srping MVC تكامل Springfox كمثال لمناقشة استخدام ومبادئ SpringFox.
خطوات لدمج springmvc في springfox
أولاً ، يحتاج المشروع إلى إضافة التبعيات الثلاثة التالية:
<!-Sring MVC التبعية-> <redency> <roupiD> org.springframework </rougeid> <StifactId> Spring-Webmvc </shintifactid> <sophy> 4.2.8.Release </version> </dependency> <! <StifactId> springfox-swagger2 </stifactId> <soper> 2.6.1 </version> </repreadency> <!-يوفر Swagger-Ui واجهة عرض واختبار API للمشاريع-> <redency> <rouped> io.springfox </groupid>
التبعيات الثلاثة المذكورة أعلاه هي التبعيات الأساسية لتكامل المشروع SpringMVC و Springfox ، وتم حذف التبعيات الأخرى هنا. الأول هو التبعية الأساسية لـ SpringMVC ، والثاني هو التبعية Swagger ، والثالث هو التبعية المتعلقة بالواجهة. هذا ليس ضروريًا. إذا كنت لا ترغب في استخدام واجهة API التي تأتي مع Springfox ، فيمكنك أيضًا استخدام هذا ، وكتابة مجموعة من الواجهات التي تناسب مشروعك. بعد إضافة هذه التبعيات ، سيضيف النظام تلقائيًا بعض حزم الجرة المتعلقة بـ Springfox و Swagger. ألقيت نظرة موجزة ووجدت أن هناك بشكل أساسي ما يلي:
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
الجوافة 17.0.JAR
Spring-Plugin-Core-1.2.0.Release.Jar
Spring-plug-metadata-1.2.0.Release.Jar
Spring-swagger-ui-2.6.1.jar
جاكسون دياتابيند -2.2.3.jar
Jackson-Annotations -2.2.3.jar
ما سبق هو الجرار التي أعتقد بصريًا قد تحتاجها Springfox ، وقد لا توضح تمامًا جميع الجرار التي يحتاجها Springfox. من الجرة المذكورة أعلاه ، يمكننا أن نرى أنه بالإضافة إلى الاعتماد على Swagger ، يتطلب Pringfox أيضًا الجوافا ، و SPRING-Plug ، و Jackson وغيرها من التبعيات (لاحظ أن Jackson هي حزمة جرة ضرورية لتوليد JSON.
استخدام بسيط لـ Springfox
إذا كنت تستخدم فقط التكوين الافتراضي لـ SpringFox ، فإن الاندماج مع SpringMVC أمر بسيط للغاية. فقط اكتب فصلًا مشابهًا للرمز التالي ووضعه في مشروعك. الرمز كما يلي:
@configuration@enablewebmvc@enlobeswagger2publicclass apiconfig {}لاحظ أنه أعلاه هو ملف فئة Java فارغ ، يمكن تحديد اسم الفصل في الإرادة ، ولكن يجب إضافة التعليقات التوضيحية الثلاثة التي تحمل علامة Configuration و enableWebmvc و @enleswagger2 في الفئة أعلاه. هذا يكمل التكامل الأساسي لـ SpringMVC و Springfox. مع ثلاثة تعليقات توضيحية ، بعد بدء المشروع ، يمكنك استخدام عنوان مما يلي مباشرة لعرض قائمة API: http://127.0.0.1:8080/jaddemo/swagger-ui.html
هذا بالفعل تأثير سحري للغاية. مع ثلاثة تعليقات توضيحية بسيطة ، سيعرض النظام تلقائيًا جميع واجهات برمجة التطبيقات لجميع فئات وحدة التحكم في المشروع. الآن ، لنبدأ بفئة التكوين هذه ونحل تحليل مبادئها ببساطة. لا يوجد رمز في هذا الفصل ، ومن الواضح أن التعليقات التوضيحية الثلاثة تلعب دورًا حاسمًا. من بينها ، توضيح التكوين المتاح بالفعل في إطار الربيع. إنه تعليق توضيحي تم تحديده بواسطة التعليق التوضيحي meta @component. لذلك ، مع هذا التعليق التوضيحي ، سيقوم Spring تلقائيًا بتسوية الفصل في الفول وتسجيله في سياق الربيع. وبالتالي ، فإن التعليقات التوضيحية الثانية enableWebMVC تعني أن SRPingMVC تم تمكينه. انقر فوق هذا التعليق التوضيحي في Eclipse لإلقاء نظرة قصيرة. إنه لأغراض الفاصوليا من النوع الذي يفوضها عناوين في سياق الربيع من خلال التعليق التوضيحي meta (devatingwebmvcConfiguration.class). أعتقد أن الغرض من هذا الفصل يجب أن يكون توفير Swagger مع بعض تكوين SpringMVC. التعليقات التوضيحية الثالثة: @enbleswagger2. يمكنك التفكير في الاسم. يتم استخدامه لدمج Swagger 2. من خلال التعليق التوضيحي meta: import ({swagger2documentationConfiguration.class}) ، قدمت Swagger2documentationConfiguration نوع تكوين نوع التكوين ، وهذا هو التكوين الأساسي للتبخيل. الرمز بداخله هو كما يلي:
@configuration@import ({springfoxwebmvcconfiguration.class ، swaggerCommonConfiguration.class})@componentscan (basePackages = {"springfox.documentation.swagger2 "springfox.documentation.swagger2.mappers"}) PublicClassSwagger2DocumentationConfiguration {bean public jacksonmoduleregistrar swagger2module () {returnnewswagger2jacksonmodule () ؛ }}يستخدم رأس الفئة هذا بعض التعليقات التوضيحية ، ثم يقدم فئة SpringfoxWebMVCConfiguration وفئة التكوين SwaggerCommonConcon ، ويفحص الفاصوليا المرتبطة بـ springfox .swagger2 في سياق الربيع من خلال التعليق التوضيحي للمكونات. هنا ، ما يهمني أكثر هو فئة springfoxwebmvcconfiguration. أعتقد أن هذا الفصل يجب أن يكون التكوين الأساسي لـ MVC المتكامل لـ SpringFox. انقر في وشاهد الرمز التالي:
@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 ، kearbuilderplugin.class ، parameterbuilderplugin.class ، expensedParameterBuilderPlugin.clas pathdecorator.class})الكود التالي في هذه الفئة ليس أكثر من إضافة بعض الفاصوليا الجديدة من خلال التعليق التوضيحي bean. أنا لست مهتمًا جدًا به. أكثر ما يهمني هو الأشياء التي تمت إضافتها إلى الرأس من خلال enablePlugInregistries. يعتمد Springfox على آلية spring-plug لدمج Swagger. كيف يتم تنفيذ spring-plug؟ ليس لدي وقت لدراسة مبدأ spring-plug حتى الآن. لكن أدناه ، سأذكر أنني أكتب مكونًا إضافيًا لتوسيع وظائف Swagger. القابس المضافة أعلاه من خلال enablePlugInregistries غير متوفر بعد. تتضمن الرموز التي رأيتها بشكل أساسي apilistingbuilderplugin.class ، kearbuilderplugin.class ، parameterbuilderplugin.class ، expensedparameterbuilderplugin.class ، expensedParameterBuilderPlugin.class ،
أول apilistingbuilderplugin ، التي لديها فئتين للتنفيذ ، وهما apilistingreader و swaggerapilistingreader. من بينها ، ستقوم ApilistingReader تلقائيًا بإنشاء قائمة API وفقًا لنوع وحدة التحكم ، وسيقوم SwaggerApilistingReader بإنشاء قائمة API وفقًا للتصنيف المحدد بواسطة التعليق التوضيحي api. يتم استخدام المكون الإضافي لـ OperationBuilderPlugin لإنشاء مستندات API محددة. يحتوي هذا النوع من المكون الإضافي على العديد من فئات التنفيذ. كل منهم يقسمون عملهم ويقومون بأشياءهم الخاصة. لم أنظر إلى التفاصيل بعناية ، لكنني ركزت فقط على أحد فئات التنفيذ: ProseparameterReader. هذه الفئة عبارة عن مكون إضافي يستخدم لقراءة معلمات API. يعتمد على فئة أداة ModelAttributeParameterexpander ، والتي يمكنها تلقائيًا تحليل كائنات الأوامر من النوع غير البسيط في معلمات طريقة الواجهة في وحدة التحكم للحصول على قائمة معلمات تحتوي على جميع السمات (هناك حفرة قد تسبب تكرارًا غير محدود ، والتي تم تقديمها أدناه). يتم استخدام مكون الإضافات expressedParameterBuilderPlugin بشكل أساسي لتوسيع بعض وظائف معلمات الواجهة ، مثل تحديد نوع البيانات لهذه المعلمة وما إذا كانت معلمة ضرورية لهذه الواجهة ، إلخ. عند بدء تشغيل النظام ، يتم ضبطه ، يتم استخدام بعضها لمسح قائمة الواجهة ، ويتم استخدام بعضها لقراءة معلمات الواجهة ، وما إلى ذلك. الغرض المشترك هو مسح جميع واجهات واجهة برمجة التطبيقات في النظام وتذوقها للمستخدمين لعرضها. لذا ، كيف يتم ضبط هذه السلسلة من سدادات الجدول وأين يتم تنفيذ مداخل التنفيذ؟
وضعنا نقطة انتباهنا على محتوى شرح مكونات مكونات في رأس الكود لفئة springfoxwebmvcConfiguration أعلاه. في هذا التعليق التوضيحي ، تم مسح حزمة تسمى springfox.documentation.spring.web.plugins. يمكن العثور على هذه الحزمة في springfox-spring-web-2.6.1.jar. تحت هذه الحزمة ، وجدنا أن هناك فئتان أساسيتان للغاية ، وهما DocumentationPluginsManager و DocumentationPluginsBootStrapper. بالنسبة للتوثيق الأول pluginsmanager ، فهي عبارة عن حبة لا تنفذ أي واجهة ، ولكنها تحتوي على العديد من خصائص نوع المكونات الإضافية ، ويتم حقنها جميعها في قيمة الخاصية من خلال التعليق التوضيحي @Autowired. الجمع بين اسم الفصل ، من السهل التفكير في أن هذا هو المدير الذي يدير جميع المقابس. من السهل الفهم ، بسبب تكوين شرح مكونات Componentscan ، سيتم إنشاء جميع مثيلات المكونات في فول بحلول الربيع ، ثم حقنها في مثيل الوثائق PluginsManager وإدارتها بشكل موحد. فئة أخرى مهمة في هذه الحزمة documentationpluginsbootstrapper ، يمكنك تخمين من خلال النظر إلى الاسم ، قد يكون فئة بدء التشغيل. عند النقر فوق التفاصيل والإلقاء نظرة عليها ، ستجد أنه بالفعل مكون تم تحديده بواسطة component ، وتؤدي طريقة البناء الخاصة به إلى حقن مثيل DocumentationPluginsManager الموصوفة للتو ، والشيء الأكثر أهمية هو أنه ينفذ أيضًا واجهة SmartLifecycle. يعرف أي شخص يعرف دورة حياة حبوب الربيع أنه عندما يتم إنشاء هذا المكون في حبة ويتم إدارته في سياق Srping ، سيتم استدعاء طريقة البدء () تلقائيًا. عند النقر فوق start () للنظر في الكود ، ستجد أنه يحتوي على سطر من الكود scandocumentation (buildContext (كل)) ؛ الذي يستخدم لمسح مستندات API. من خلال تتبع رمز هذه الطريقة ، يمكنك العثور على أن هذه الطريقة ستستخدم في النهاية خاصية DocumentationPluginsManager لضبط جميع المقابس معًا لمسح النظام بأكمله وإنشاء مستندات API. يتم تخزين نتائج الفحص في خاصية MAP لفئة DocumentationCache.
ما سبق هو المبدأ العام لـ SrpingMVC دمج Springfox. يقوم بشكل أساسي بحقن سلسلة من الفاصوليا في سياق Srping من خلال التعليق التوضيحي EnloberWagger2 ، ويفحص فئة وحدة تحكم النظام تلقائيًا عند بدء تشغيل النظام ، ويولد معلومات API المقابلة ويختفي. بالإضافة إلى ذلك ، فإنه يقوم بحقن بعض فئات وحدة التحكم التي تم تحديدها بواسطة @Controller enootation كإدخال لوحدة واجهة المستخدم للوصول إلى قائمة API. على سبيل المثال ، فئة Swagger2Controller في حزمة Springfox-Swagger2-2.6.1.jar. وحدة التحكم هذه هي عنوان الواجهة المستخدم في وحدة واجهة المستخدم للوصول إلى قائمة API. عند زيارة العنوان http://127.0.0.1:8080/jaddemo/swagger-ui.html لعرض قائمة API ، يمكنك أن ترى من خلال المتصفح أنه من غير المتزامن الحصول http://127.0.0.1:8080/jaddemo/v2/api-docs؟group=sysgroup وعرضه على الواجهة. إدخال وحدة التحكم المقابلة لخلفية هذا العنوان هو فئة Swagger2Controller أعلاه. بعد تلقي الطلب ، تجلب هذه الفئة مباشرة معلومات API من ذاكرة التخزين المؤقت التي تمت تهيئتها مسبقًا لإنشاء عودة سلسلة JSON.
بعد فهم مبادئ Springfox ، دعونا نلقي نظرة على المزالق التي واجهتها أثناء استخدام Springfox.
أول حفرة كبيرة من Springfox: يجب أن تشارك الفاصوليا التي تم إنشاؤها بواسطة فئة التكوين نفس سياق Spring MVC.
كما هو موضح أعلاه ، في مشروع SpringMVC ، فإن دمج SpringFox هو مجرد كتابة فئة تكوين بسيطة على النحو التالي دون أي رمز عمل في المشروع.
@configuration@enablewebmvc@enlobeswagger2publicclass apiconfig {}نظرًا لشرح التعليق التوضيحي لـ Configuration ، سيقوم Spring تلقائيًا بتسويةه في الفول ويحقنه في السياق. ولكن أحد المآزق التي يجب الإشارة إليها هو أن السياق الذي يجب أن يكون فيه هذه الفول في نفس سياق SPRING MVC. كيف تفهم؟ لأنه في مشاريع الربيع الفعلية MVC ، عادة ما يكون هناك سياقان ، أحدهما يتبع السياق والآخر هو الربيع MVC (وهو نص فرعي يتبع السياق). السياق هو org.springframework.web.context.request.requestContextListener المستمع المتعلقة بـ Spring في ملف web.xml. عادةً ما يتم كتابة السياق المحمّل كملف تكوين يسمى spring-contet.xml. سيتم تهيئة الفاصوليا هنا في النهاية إلى السياق. ويشمل بشكل رئيسي الخدمة ، DAO والفاصوليا الأخرى في النظام ، وكذلك مصادر البيانات ، الأشياء ، إلخ عادة ما يكون لديه ملف تكوين يسمى spring-mvc.xml. عند كتابة فئة APICONFIG ، إذا قررنا تحميلها باستخدام شرح التكوين @، يجب علينا التأكد من أن مسار هذه الفئة ضمن نطاق الحزمة الأساسية لتكوين المكون المسح في SPRINGMVC. لأنه عندما يتم تحميل apiconfig بحلول الربيع ، سيتم حقن سلسلة من الفاصوليا. في هذه الفاصوليا ، من أجل مسح جميع فئات وحدة التحكم تلقائيًا ، تحتاج بعض الفاصوليا إلى الاعتماد على بعض الفاصوليا في springmvc. إذا كان المشروع يفصل سياق SRPingMVC عن السياق كنص فرعي للسياق. إذا سمحت بطريق الخطأ بتحميل هذا الفول من نوع Apiconfig بالنص السابق ، لأنه لا توجد فئات تكوين في سياق SPRING MVC في سياق الجذر.
في الواقع ، لا أتفق مع تكوين Swagger من خلال التعليق التوضيحي لـ Configuration ، لأنني أعتقد أن وظائف API الخاصة بـ Swagger اختياري لمشاريع الإنتاج. غالبًا ما يتم استخدام Swagger لدينا لاختبار البيئات لتطوير الفريق الأمامي للمشروع أو أنظمة أخرى لدمج الواجهات. بمجرد أن يكون النظام متصلاً بالإنترنت ، من المحتمل أن يتم إخفاء قوائم API هذه على نظام الإنتاج. ولكن إذا تمت كتابة التكوين في رمز Java من خلال التعليق التوضيحي لـ Configuration ، فعندما تريد إزالة هذه الوظيفة عند الاتصال بالإنترنت ، فسيكون ذلك محرجًا وعليك تعديل رمز Java لإعادة الترجمة. بناءً على ذلك ، أوصي طريقة لتكوين ملف XML الأكثر تقليدية بحلول الربيع. تتمثل الطريقة المحددة في إزالة شرح التكوين @، ثم يكتب تكوين الفاصوليا مماثلة لـ <bean/> في ملف تكوين XML Spring. في المشروع الذي يتم فيه فصل سياق الجذر عن سياق MVC ، يتم تكوينه مباشرة إلى spring-mvc.xml ، مما يضمن أنه يجب أن يكون في نفس سياق SPRINGMVC.
ثاني أكبر حفرة من Springfox: معلمات فئة وحدة التحكم ، انتبه لمنع العودية اللانهائية.
لدى Spring MVC آلية ربط معلمة قوية ، والتي يمكن أن تربط معلمات الطلب تلقائيًا في كائن أمر مخصص. لذلك ، لكي تكون كسولًا ، يستخدم العديد من المطورين كائن كيان مباشرة كمعلمة لطريقة وحدة التحكم عند كتابة وحدة تحكم. على سبيل المثال ، رمز المثال التالي:
requestmapping (value = "update") تحديث السلسلة العامة (menuvomenuvo ، نموذج النموذج) {}هذا هو الرمز الذي يحب معظم المبرمجين الكتابة في وحدة التحكم لتعديل كيان. عند الاندماج مع Swagger ، هناك حفرة كبيرة هنا. إذا كانت جميع الخصائص في Menuvo هي أنواع أساسية ، فلا بأس ، لا شيء يحدث بشكل خاطئ. ولكن إذا كان هناك بعض سمات النوع المخصص الأخرى في هذه الفئة ، وهذه السمة موجودة بشكل مباشر أو غير مباشر سمات من نوعها الخاصة ، فستكون هناك مشاكل. على سبيل المثال: إذا كانت فئة Menuvo هي فئة قائمة ، فإنها تحتوي أيضًا على أحد الوالدين من نوع Menuvo الذي يمثل القائمة الأم. وبهذه الطريقة ، ستقوم وحدة Swagger بالإبلاغ مباشرة عن خطأ عند بدء تشغيل النظام لأنه لا يمكن تحميل واجهة برمجة التطبيقات. سبب الخطأ هو أنه عند تحميل هذه الطريقة ، سيتم تحليل معلمات طريقة التحديث. عندما لا تكون المعلمة Menuvo نوعًا بسيطًا ، سيتم تفسير جميع سمات الفصول الدراسية تلقائيًا بشكل متكرر. هذا يجعل من السهل الوقوع في حلقة ميتة من العودية اللانهائية.
من أجل حل هذه المشكلة ، كتبت للتو فئة تنفيذ ProgressParameterReader و Class ModelAttributeParameterexpander Class التي يعتمد عليها. يحل محل الفئتين الأصليتين من srpingfox من خلال التكوين ، ويحل محل منطق تحليل تحليل المعلمة مثل العمود ، ويتجنب عودية لا حصر لها. بالطبع ، هذا يعادل طريقة لتعديل مستوى التعليمات البرمجية. لم أجد حلاً أكثر مثالية لهذه المشكلة حتى الآن ، لذلك لا يمكنني إلا أن أوصي بأن تحاول تجنب هذا التكرار اللانهائي عند استخدام SPRING-Fox Swagger. بعد كل شيء ، هذا لا يتوافق مع مواصفات كائنات أمر springMVC. من الأفضل أن تكون كائنات الأوامر مع معلمة springMVC فقط سمات النوع الأساسي البسيط.
الحفرة الرئيسية الثالثة لـ Springfox: API ذات الصلة ، لا يمكن تحميل مثيلات DOCKET
سوف Springfox تقسيم جميع واجهات برمجة التطبيقات إلى مجموعة بشكل افتراضي. عندما يتم الوصول إليها من خلال عنوان مشابه لـ http://127.0.0.1:8080/jaddemo/swagger-ui.html ، سيتم تحميل جميع قوائم API على نفس الصفحة. وبهذه الطريقة ، إذا كان النظام أكبر قليلاً وكان واجهة برمجة التطبيقات أكثر من ذلك بقليل ، فستكون الصفحة مزيفة حتى الموت ، لذلك من الضروري للغاية تجميع واجهة برمجة التطبيقات. يتم تعريف تجميع API بواسطة التعليق التوضيحي bean في ملف تكوين APICONF. التكوينات الشائعة على الإنترنت هي كما يلي:
@enablewebmvc@enlobeswagger2publicClass Apiconfig {bean public docket customDocket () {return newDocket (documentationType.swagger_2) .Apiinfo (apiinfo ()) ؛ }}في الكود أعلاه ، يتم حقن جدول من خلال bean. هذا التكوين ليس ضروريًا. إذا لم يكن هذا التكوين متاحًا ، فسيقوم الإطار بإنشاء مثيل DOCKET الافتراضي بنفسه. الغرض من مثيل Docket هذا هو تحديد المعلومات العامة لجميع واجهات برمجة التطبيقات التي يمكن أن تديرها ، مثل المعلومات الأساسية مثل إصدار API ، المؤلف ، وما إلى ذلك ، وتحديد واجهات برمجة التطبيقات المدرجة فقط (التي يتم ترشيحها بواسطة عناوين API أو التعليقات التوضيحية).
يمكن أن يكون هناك العديد من حالات الإجراءات ، مثل الرمز التالي:
@enablewebmvc@enlobeswagger2publicclass apiconfig {bean public docket customDocket1 () {return newDocket (documentationType.swagger_2) .groupname (apigroup1 "). apiinfo (apiinfo ()). } bean public docket customDocket2 () {return newDocket (documentationType.swagger_2) .GroupName ("Apigroup2"). Apiinfo (apiinfo ()). }}عند تكوين مثيلات DOCKET متعددة في المشروع ، يمكن تجميع API ، على سبيل المثال ، يقسم الكود أعلاه واجهة برمجة التطبيقات إلى مجموعتين. في هذه الحالة ، يجب تعيين كل مجموعة اسمًا مختلفًا ، مثل "APIGROUP1" و "Apigroup2" في الكود أعلاه. يمكن لكل مجموعة استخدام مسارات لتحديد المجموعة التي يمكنك إدارة واجهات برمجة التطبيقات من خلال تعبير عنوان النملة. على سبيل المثال ، في التكوين أعلاه ، المجموعة الأولى من عناوين الإدارة هي واجهات برمجة التطبيقات مع بداية /sys /. المجموعة الثانية من واجهات برمجة التطبيقات الإدارية مع بداية /متجر /. بالطبع ، هناك العديد من أساليب التصفية الأخرى ، مثل التعليق التوضيحي للصف ، وشرح الطريقة ، ومعالجة التعبيرات العادية ، وما إلى ذلك. بعد التجميع ، يمكنك تحديد مجموعات API مختلفة في الخيار المنسدلة في الزاوية اليمنى العليا من واجهة قائمة API. سيؤدي ذلك إلى تفريق قائمة API للمشروع إلى صفحات مختلفة. سيسهل هذا الإدارة دون التظاهر بأنها ميتة لأن الصفحة تحتاج إلى تحميل الكثير من واجهات برمجة التطبيقات.
ومع ذلك ، مثل استخدام @configuration ، لا أتفق مع استخدام bean لتكوين مثيلات docket لتجميع واجهات برمجة التطبيقات. لهذا السبب ، سيتم كتابة الرمز أيضًا حتى الموت. لذلك ، أوصي بتكوين مثيل Docket الخاص بك في ملف XML لتنفيذ هذه الوظائف المماثلة. بالطبع ، بالنظر إلى العديد من السمات في القائمة ، من المثير للقلق تكوين الفاصوليا مباشرة. يمكنك كتابة مصنع للقرعة بنفسك ثم تكوين Factorybean في ملف XML. ومع ذلك ، عند تكوين Docket في XML. ستواجه حفرة كبيرة أخرى ، أي أن طريقة التحميل للنسخ على الفاصوليا محملة بشكل افتراضي. بعد تكوين فاصوليا مثيل Docket مباشرة في XML. ستجد أنه لا يوجد أي تأثير ، ولا يوجد عنصر تجميع في القائمة المنسدلة في الزاوية اليسرى العليا من الصفحة.
هذه المشكلة قد أزعجتني لعدة ساعات. في وقت لاحق ، استنادًا إلى الخبرة ، تم التكهن أنه قد يكون ذلك لأن حبة الربيع يتم تحميلها كسولًا بشكل افتراضي ، ولم يتم تحميل مثيل Docket هذا في سياق الربيع. كما اتضح ، تخميني صحيح. لا أعرف ما إذا كان هذا خطأ في Springfox ، أو إذا لم يكن ينبغي علي نقل تكوين Docket من رمز Java الأصلي إلى ملف تكوين XML.
عيوب أخرى في Springfox: هناك بعض المزالق الأخرى في Springfox. على سبيل المثال ، في شرح apiOperation ، إذا لم يتم تحديد سمة httpmethod كطريقة GET أو POST معينة ، فسيتم إدراج جميع الأساليب مثل GET أو POST أو DELETE أو PUT في قائمة API ، بحيث يتم تكرار قائمة واجهة برمجة التطبيقات أكثر من اللازم. بالإضافة إلى ذلك ، أثناء الاختبار ، واجهت مشكلات إذن تسجيل الدخول ، إلخ. هذه أكوام من الحفر الصغيرة التي يسهل حلها ، بسبب المساحة المحدودة ، لن أقول الكثير. هناك أيضًا استخدام التعليقات التوضيحية مثل api و apiOperation و apiParam. لن أكرر العديد من المستندات على هذا عبر الإنترنت.
ما سبق هو كل محتوى هذه المقالة. آمل أن يكون ذلك مفيدًا لتعلم الجميع وآمل أن يدعم الجميع wulin.com أكثر.