كانت مستندات الواجهة الخارجية دائمًا بدائية نسبيًا ، ويتم تمرير المستندات المكتوبة بخط اليد بشكل أساسي. لقد اكتشفت مؤخرًا لعبة جديدة ، والتي يمكن أن توفر الكثير من المتاعب على الواجهة.
Swagger هو إطار توثيق API مناسب. يمكن أن يعرض نوع الواجهة للمطور الآخر بالطريقة الأكثر شمولاً ، وتجنب السلوك أحادي الجانب والخطأ للمستندات المكتوبة بخط اليد.
يوجد حاليًا نوعان من Swagger و Swagger2. 1 أكثر إثارة للقلق ، لذلك لا تفكر في استخدامه. تسجل هذه المقالة بشكل أساسي طريقتين أستخدمه Swagger2 كواجهة خارجية. يرجى التحقق منه لاحقًا.
1. استخدم springmvc التقليدية لدمج swagger2
1. تبعية مافن
<!-تبعيات Springfox-> <redency> <roupiD> com.fasterxml.jackson.core </rougiD> <ArtifactId> Jackson-Core </frintifactid> <الإصدار> 2.8.0 </version> </repataDency> </depatabency> <soph> 2.6.3 </version> </sependency> <redency> <roupiD> com.fasterxml.jackson.core </rougeid> <StifactId> annotations-annotations </insifactid> <splement> 2.6.3 </version> <StifactId> springfox-swagger2 </shintifactid> <الإصدار> 2.4.0 </version> </respency> <reperency> <roupled> io.springfox </rougeid> <StifactId> springfox-swagger-ui </stifactid> <splem>
2. أضف تكوين تعيين ثابت في spring-mvc.xml (في الواقع ، يمكنني إزالة هذا في مشروعي ، لا أعرف ما هو الموقف):
<!-مسار الملف الثابت Swagger-> <mvc: موقع الموارد = "classpath:/meta-inf/" mapping = "swagger-ui.html"/> <mvc: resources location = "classpath:/meta-inf/webjars/" mapping = "/webjars/**"/>
ملاحظة: لن أنشر تكوين SpringMVC الأساسي. تجدر الإشارة إلى أنه إذا رأيت واجهة Swagger-ui.html تخرج ، لكنها فارغة ، فيرجى التحقق من تكوين التقاطع في web.xml. يجب أن تعترض springmvc أولاً ، ثم سيتم عرض الواجهة.
3. ثم هناك فئة التكوين من Swagger2:
@configuration @enlobeswagger2public class swaggerConfig يمتد webmvcconfigurationsupport .Paths (PathSelectors.Any ()) .Build () ؛ } apiinfo apiinfo () {إرجاع apiinfobuilder () }}ملاحظة: إذا كان من الممكن ضبط المسارات على PathSelectors.NONE () في الإنتاج ، فإنها لا تعرض جميع معلومات الواجهة ؛
4. تكوين معلومات الواجهة
أي تكوين معلومات الواجهة ذات الصلة في وحدة تحكم springMVC
@controller@requestMapping (value = "aitou")@API (description = "اختبار معلومات حساب الخدمة") الفئة العامة DailyOperationDataController {logger logger = logger.getLogger (DailyOperationDataController.class) ؛ @autowired DailyOperationDationDataservice DailyOperationDataservice ؛ / * * * apiOperation (value = "الواجهة الوصف" ، httpmethod = "طريقة طلب الواجهة" ، response = "نوع الواجهة إرجاع المعلمة" ، Notes = "interface relext note" = {requestMethod.post ، requestMethod.get} ، value = "/Query/DailyData/{datadate}") @responsebody public dailyoperationdto getDailyReportBortAdatate (pathvariable ("datadate") (استثناء e) {logger.error (e.getMessage () ، e) ؛ملاحظة: عادةً ما يعرض Swagger2 جميع الواجهات ضمن حزمة المسح. أنا هنا الواجهة الخارجية لأكون حزمة منفصلة لتجنب عرض العديد من الواجهات. بالطبع ، يمكن أن تمنعها طريقة الواجهة أيضًا من العرض. يمكنك رؤية التعليقات التوضيحية ذات الصلة أدناه.
بعض الملاحظات شائعة الاستخدام
api: تستخدم في فصل لتوضيح وظيفة الفصل
apiOperation: يستخدم في طرق لتوضيح وظيفة الأساليب
apiimplicitparams: تستخدم لتضمين مجموعة من أوصاف المعلمة على الطريقة
apiImplicitParam: يستخدم في apiImplicitParams annotation ، حدد جوانب مختلفة من معلمة request paramtype: أين تضع المعلمة ・ header -> احصل على معلمة طلب: requestheader
・ استعلام -> طلب الاستحواذ على المعلمة: requestparam
・ المسار (للواجهة المريحة) -> احصل على معلمات الطلب: pathvariable
・ الجسم (غير شائع الاستخدام)
・ الشكل (غير شائع الاستخدام)
الاسم: اسم المعلمة نوع البيانات: نوع المعلمة المطلوب: ما إذا كان يجب تمرير المعلمة القيمة: المعلمة معنى DefaultValue: المعلمة القيمة الافتراضية
apiResponses: تستخدم لتمثيل مجموعة من الردود
apiresponse: يستخدم في apiResponses ، ويستخدم بشكل عام للتعبير عن رمز استجابة الخطأ: رقم ، مثل 400
الرسالة: الرسالة ، مثل "معلمة الطلب لا يتم ملؤها"
الرد: الفصل الذي يلقي الاستثناء
apiParam: وصف معلمة واحدة
apImodel: صف معلومات نموذج ما ويستخدم الكائنات لتلقي المعلمات (عادة ما يتم استخدام هذا عند إنشاء منشورات ، وذلك باستخدام سيناريوهات requestbody ، وعند طلب المعلمات لا يمكن وصفها باستخدام apiImplicitparam التعليق التوضيحي)
apimodelproperty: صف خصائص النموذج
apiProperty: عند استخدام كائن لتلقي المعلمات ، وصف حقل الكائن
apiignore: استخدم هذا التعليق التوضيحي لتجاهل واجهة برمجة التطبيقات هذه
في الأساس ، كل ما سبق. أليس من السهل جدا؟ لنرى صورة التأثير أدناه
2. استخدم Springboot لدمج Swagger2
المذكورة أعلاه باستخدام springMVC التقليدية لدمج swagger2. دعنا نتحدث عن طريقة Springboot الشعبية الأخيرة. في الواقع ، المبادئ هي نفسها.
1. تبعية مافن
<!-springfox rependency-> <redency> <roupiD> io.springfox </groupId> <StifactId> springfox-swagger2 </stifactid> <sophy> 2.7.0 </spertic> </dependency> <sperence> <roucid> io.springfox </groupid> <splect> 2.7.0 </version> </premency>
هذا هو الاستخدام الداخلي لمشروعي الشخصي الذي كتبته مؤخرًا باستخدام Springboot ، ويستخدم الإصدار المستخدم 2.7.0 في الإصدار.
2. إضافة تكوين الموارد الثابتة
ConfigurationPublic Class WebMVcConfig يمتد webmvcConfigureRadapter {/ ** * تكوين مسار المورد الثابت والمسار لتحميل الملف * * @param registry */ Override public void addresourceHandlers (ResourceHandlerRegistry Recistry) { registry.addresourceHandler ("/static/**"). addresourcelocations ("classpath:/static/") ؛ registry.addresourceHandler ("/expload/**"). addresourcelocations (البيئة. /*swagger-ui*/registry.addresourceHandler ("swagger-ui.html"). addresourcelocations ("classpath:/meta-inf/resources/") ؛ registry.addresourceHandler ("/webjars/**"). addresourcelocations ("classpath:/meta-inf/resources/webjars/") ؛ }}في الواقع ، إنها فقط الجملتين. إذا لم تقم بتكوين هذا ، فسترى خطأ 500 أو 404 عند زيارة Swagger-ui.html. إذا لم تتمكن من تذكرها ، فيجب أن يكون 404.
3. فئة التكوين Swagger2
مثل ما سبق ، لا يوجد فرق في الأساس
@configuration@enbleswagger2@enablewebmvcpublic class swaggerConfig يمتد webmvcConfigurationSupport {bean public docket createrestapi () {return new docket (documentationType.swagger_2). .Apis (requestHandlersElectors.BasePackage ("net.laoyeye.yyblog.web.frontend") .paths (pathselectors.none ()) .build () ؛ } apiinfo apiinfo () {إرجاع apiinfobuilder () }}لاحظ أن لدي مشكلة في المسار أعلاه. لا تعرض النسخة مباشرة واجهة برمجة التطبيقات (#^.^#)
4. تكوين الواجهة
/*** وحدة تحكم مقالة مكتب الاستقبال* Author Grandpa في المتجر الصيفي* date 5 مايو ، 2018* WebBsite www.laoyeye.net*/ @api (description = "article query") @controller @requestMapping ("/article") public class articlecontroller Autowired SettingService SettingService ؛ @Autowired Cateservice Cateservice ؛ Autowired private tagreferservice tagreferservice ؛ @Autowired userverservice uservice ؛ @autowired articlemapper articlemapper ؛ @autowired تعليقات خاصة التعليقات ؛ apiOperation (value = "article query Query Interface") apiImplicitParam (name = "id" ، value = "article ide" ، required = true ، datatype = "long") getMapping ("/{id}") فهرس السلسلة العامة (نموذج نموذج ، pathvariable ("id") } catch (استثناء تجاهل) {} قائمة <Setting> الإعدادات = SettingService.Listall () ؛ خريطة <string ، object> map = new hashmap <string ، Object> () ؛ لـ (إعداد الإعداد: الإعدادات) {map.put (setting.getCode () ، setting.getValue ()) ؛ } مقال = articleservice.getArticleByid (id) ؛ model.addattribute ("الإعدادات" ، الخريطة) ؛ model.addattribute ("catelist" ، catevoryservice.listallcate ()) ؛ model.addattribute ("مقال" ، مقال) ؛ Model.AdDattribute ("Tags" ، TagReferservice.ListNameByarticleId (article.getID ())) ؛ model.addattribute ("uptor" ، uservice.getNickNameById (article.getauthorid ())) ؛ // تغيير نموذج. model.addattribute ("مماثلة" ، articlemapper.listarticlebytitle (null)) ؛ CommentQuery Query = New CommentQuery () ؛ Query.SetLimit (10) ؛ Query.SetPage (1) ؛ Query.SetArticleId (id) ؛ Model.AdDattribute ("التعليقات" ، Commentervice.ListCommentByArticleId (Query)) ؛ إرجاع "الواجهة/المقالة" ؛ } apiOperation (value = "واجهة استعلام ArticleComment") postmapping ("/comments") datagridresult public responsebody (استعلام التعليق) {// تعيين الافتراضي 10 query.setlimit (10) ؛ Return CommentService.ListCommentByArticleId (Query) ؛ } apiOperation (value = "articlelid") apiImplicitParam (name = "altchalId" ، value = "alticalId" ، required = true ، datatype = "long") postmapping ("/contrveServiceerviceIdeIdeIdeIdeIdeIdeIdeIdeIdeIdeIdeIdiDeAdiDeaId (introveAdaIdeIdeAdiD. }}أخيرًا ، هناك عرض ، كما هو مذكور أعلاه.
عندما يكون pathselectors.none () هو
عندما يكون pathselectors.any () هو
من الواضح في لمحة ما إذا كان محتوى الواجهة هو العرض ، وهو موجز وواضح للغاية.
أخيرًا ، يبدو أنني نسيت أن أقول إن الطريق إلى وثيقة Swagger
إذا كان مشروعك في دليل الجذر: http: // localhost: 8080/swagger-ui.html
إذا لم يكن الدليل الجذر ، فهو: http: // localhost: 8080/اسم المشروع/swagger-ui.html
ما سبق هو كل محتوى هذه المقالة. آمل أن يكون ذلك مفيدًا لتعلم الجميع وآمل أن يدعم الجميع wulin.com أكثر.