شرح مفصل للخطوات الكاملة لدمج Swagger2 Swagger2

مقدمة

Swagger ، المعنى الصيني "ابتلاع". إنه إطار API قوي ، وتكامله بسيط للغاية ، ولا يوفر فقط مراجعة الوثائق عبر الإنترنت ،
أيضا ، يتم توفير الوثائق عبر الإنترنت. بالإضافة إلى ذلك ، من السهل بناء واجهات برمجة تطبيقات على غرار مصادفة.

1. نظرة عامة على Swagger

Swagger هي مجموعة من الأدوات المفتوحة المصدر المبنية حول مواصفات OpenAPI للمساعدة في تصميم وبناء وتوثيق واستخدام واجهات برمجة تطبيقات REST.

ببساطة ، يبدو أنه يسهل اختبار الواجهة المريحة في الخلفية وتنفيذ التحديثات الديناميكية عندما نكون في واجهة الخلفية.

بعد التعديل ، يمكن أن يقوم Swagger بالتحديث تلقائيًا دون الحاجة إلى الحفاظ على هذه الواجهة للاختبار كما تعتقد.

2. التعليقات التوضيحية المشتركة للتبخيل

يشير Swagger من خلال التعليق التوضيحي إلى أن الواجهة ستقوم بإنشاء مستند ، بما في ذلك اسم الواجهة ، وطريقة الطلب ، والمعلمات ، ومعلومات الإرجاع ، إلخ.

• api: قم بتعديل الفصل بأكمله ووصف دور وحدة التحكم
• apiOperation: صف طريقة فئة أو واجهة
• apiParam: وصف معلمة واحدة
• apimodel: استخدم الكائنات لتلقي المعلمات
• apiProperty: عند استخدام كائن لتلقي المعلمات ، وصف حقل الكائن
• apiresponse: 1 من وصف استجابة HTTP
• apiResponses: الوصف العام للاستجابة HTTP
• apiignore: استخدم هذا التعليق التوضيحي لتجاهل واجهة برمجة التطبيقات هذه
• apierror: حدثت المعلومات التي تم إرجاعها بواسطة خطأ
• apiparamimplicitl: معلمة طلب
• apiParamSimplicit معلمات طلب متعددة

3. Springboot يدمج Swagger

3.1 إضافة تبعيات

 <Rependency> <roupEd> io.springfox </rougiD> <StifactId> springfox-swagger2 </shintifactid> <splection> 2.7.0 </version> </repreadency> <sropency> io.springfox </groupend>

3.2 إضافة تكوين SwaggerCon

من خلال تعليق التوضيح configuration ، يشير إلى أنه فئة تكوين ، و enloberwagger2 تمكين Swagger2.

APIINFO () تكوين بعض المعلومات الأساسية. تحدد APIS () أن الحزمة الممسوحة ضوئيًا ستقوم بإنشاء مستند.

بعد إنشاء فول القائمة من خلال وظيفة createrestapi ، تستخدم APIINFO () المعلومات الأساسية لواجهة برمجة التطبيقات (سيتم عرض هذه المعلومات الأساسية في صفحة المستند). تقوم دالة SELECT () بإرجاع مثيل APISELECTORBUILDER للتحكم في الواجهات التي تتعرض لتبش للعرض. يستخدم هذا المثال مسار الحزمة الممسوحة ضوئيًا لتحديدها. ستقوم Swagger بمسح جميع واجهات برمجة التطبيقات التي تحددها وحدة التحكم تحت الحزمة وإنشاء محتوى المستند (باستثناء الطلب المحدد بواسطة apiignore).

 package com.lance.learn.springbootswaggagger.configuration ؛ استيراد org.springframework.context.annotation.bean ؛ استيراد org.springframework.context.annotation.configuration ؛ springfox.documentation.builders.requesthandlerselectors ؛ import springfox.documentation.service.apiinfo ؛ import springfox.documentation.service.contact springfox.documentation.swagger2.annotations.enableswagger2 ؛/*** Author lance (zyh)* @Function Swagger STARTUP COMPLATION* date 2018-07-09 21:24*/ @ @configurn إلخ. address.paths (pathselectors.any ()) .Build () ؛ } /** * إنشاء وظيفة المعلومات التفصيلية لوثيقة واجهة برمجة التطبيقات ، ملاحظة التي يشير إلى التعليقات التوضيحية إلى * regurn * /private apiinfo apiinfo () {return new apiinfobuilder () // page title.title ( "http://www.cnblogs.com/zhangyinhua/" ، "[email protected]")) // إصدار الإصدار ("1.0") // الوصف ("API Description") .build () ؛ }}

3.3 محتوى مستند وحدة التحكم

تأتي الأوصاف بشكل أساسي من وظائف التسمية ، وما إلى ذلك ، وليست سهلة الاستخدام. عادة ما نحتاج إلى إضافة بعض الإرشادات لإثراء محتوى المستند.

كما هو موضح أدناه ، نضيف تعليمات إلى API من خلال التعليق التوضيحي apiOperation ، ونستخدم apiImplicitParams و apiimplicitparam
التعليق التوضيحي لإضافة وصف إلى المعلمات.

1) مثال 1

 package com.lance.learn.springbootswagger.controller ؛ import com.lance.learn.springbootswagger.bean.book ؛ import io.swagger.annotations.apiimplictparam ؛ import io.swagger.annotations.Apiimplication ؛ io.swagger.annotations.ApiOperation ؛ استيراد org.springframework.web.bind.annotation. * ؛ استيراد springfox.documentation.annotations.apiignore ؛ استيراد java.util. * ؛ = "/bookcurd") الفئة العامة bookController {map <long ، book> books = collections.synchronizedMap (new hashmap <long ، book> ()) ؛ apiOperation (value = "Get Book List" ، Notes = "Get Book List") REquestMapping (value = {""} ، method = requestMethod.get) قائمة عامة <book> getBook () {list <book> book = new ArrayList <> (books.values ()) ؛ كتاب العودة } apiOperation (value = "إنشاء كتاب" ، ملاحظات = "إنشاء كتاب") apiImplicitParam (name = "book" ، value = "book contity contity" ، required = true ، datatype = "book" إرجاع "النجاح" ؛ } apiOperation (value = "الحصول على معلومات مفصلة عن الكتاب" ، notes = "احصل على معلومات مفصلة بناءً على معرف url") apiImplicitParam (name = "id" ، value = "id" ، required = true ، dataType = requestMeToDeal (paramtype = "path") requestmapping (value = " id) {return books.get (id) ؛ } apiOperation (value = "معلومات التحديث" ، notes = "حدد تحديث معلومات الكتاب استنادًا إلى معرف عنوان url") apiImplicitParams ({apiImplicitParam (name = "id" ، value = "book id" ، required = true ، datatype = "long" datatype = "book")}) @requestmapping (value = "/{id}" ، method = requestMethod.put) السلسلة العامة putuser ( @pathvariable معرف طويل ، كتاب requestbody كتاب) {book Book1 = books.get (id) ؛ book1.setName (book.getName ()) ؛ book1.setPrice (book.getPrice ()) ؛ books.put (id ، book1) ؛ إرجاع "النجاح" ؛ } apiOperation (value = "delete book" ، notes = "حدد حذف الكتب بناءً على معرف url") apiImplicitParam (name = "id" ، value = "book id" ، required = true ، type type = "long" ، paramtype = "path". DELETEUSER (@pathVariable Long ID) {books.Remove (id) ؛ إرجاع "النجاح" ؛ } @apiignore // استخدم هذا التعليق التوضيحي لتجاهل API requestmapping (value = "/hi" ، method = requestMethod.get) السلسلة العامة jsontest () {return "hi you!" ؛ }}

2) مثال 2

 package com.lance.learn.springbootswagger.controller ؛ import com.lance.learn.springbootswagger.bean.user ؛ import io.swagger.annotations.apiimplictparam ؛ import io.swagger.annotations.Apiimpliciplicals ؛ io.swagger.annotations.apioperation ؛ استيراد org.springframework.web.bind.annotation. * ؛ استيراد java.util. خريطة <long ، user> users = collections.synchronizedMap (new hashmap <long ، user> ()) ؛ apiOperation (value = "get user list" ، notes = "") requestMapping (value = {"" "} ، method = requestMethod.get) قائمة عامة <Seter> getUserList () {list <ser> r = new ArrayList <Ser> (user.values ()) ؛ العودة ص. } apiOperation (value = "إنشاء مستخدم" ، ملاحظات = "إنشاء مستخدم من كائن المستخدم") apiImplicitParam (name = "user" ، value = "مستخدم كيان مفصل للمستخدم" ، مطلوب = true ، نوع dataType = "user") erquestmapping (value = "" إرجاع "النجاح" ؛ } apiOperation (value = "الحصول على تفاصيل المستخدم" ، notes = "احصل على تفاصيل المستخدم بناءً على معرف عنوان url") apiImplicitParam (name = "id" ، value = "user id" ، required = true ، dataType = "long") @redupappapping (value = "/{id}" ، method = requestmet.get) } apiOperation (value = "تحديث تفاصيل المستخدم" ، وملاحظات = "حدد تحديث الكائنات بناءً على معرف عنوان URL ، وتحديث تفاصيل المستخدم بناءً على معلومات المستخدم المرسلة") @apiImplicitParams ({{apiimpliciMAram (name = "id" ، value = "user id" المستخدم "، مطلوب = صواب ، datatype =" user ")}) @requestmapping (value ="/{id} "، method = requestMethod.put) السلسلة العامة putuser (pathvariable معرف طويل ، مستخدم مستخدم requestbody) {user u = new user () ؛ users.put (id ، u) ؛ إرجاع "النجاح" ؛ } apiOperation (value = "delete user" ، notes = "حدد حذف كائن وفقًا لمعرف url") apiImplicitParam (name = "id" ، value = "user id" ، مطلوب = true ، datatype = "long") @requestmapping (value = "{id} ، users.remove (id) ؛ إرجاع "النجاح" ؛ }}

3.4 عرض واجهة الويب

4. عنوان رمز المشروع

https://github.com/lancetobigdata/springbootlearning/tree/develop/springboot-swagger

لخص

ما سبق هو المحتوى الكامل لهذه المقالة. آمل أن يكون لمحتوى هذه المقالة قيمة مرجعية معينة لدراسة أو عمل الجميع. إذا كان لديك أي أسئلة ، فيمكنك ترك رسالة للتواصل. شكرا لك على دعمك إلى wulin.com.