إطار الربيع التمهيد حاليا بشعبية كبيرة إطار الخدمات الصغيرة، نستخدمها في كثير من الحالات لتوفير الراحة API. أما بالنسبة للAPI الراحة هو جزء مهم جدا من تلك الوثيقة، يوفر التبختر لنا طريقة لتوليد رمز وثائق تلقائيا من خلال الملاحظات، والتي هي لضمان وثائق API في الوقت المناسب سوف يساعد كثيرا. وسوف تستخدم هذه المادة التبختر 2 مواصفات تنفيذ Springfox لمعرفة كيفية استخدام التبختر في مشروع الربيع التمهيد يشمل أساسا بعض التكوين المتقدم والشرح التبختر وثائق تم إنشاؤه تلقائيا، واستخدام التبختر التبختر الوثائق ذات الصلة، وكيفية استخدامها.

التبختر الملف الشخصي

التبختر هو عبارة عن مجموعة من المواصفات بناء على أدوات مفتوحة المصدر بنيت OpenAPI يمكن أن تساعدنا على تصميم وبناء واستخدام تسجيل الراحة API. التبختر يحتوي بشكل رئيسي على الأجزاء الثلاثة التالية:

التبختر المحرر: محرر يستند إلى مستعرض، ونحن يمكن استخدامها لكتابة مواصفات لنا OpenAPI.

التبختر UI: سيكون OpenAPI مواصفات كتبنا كما عرضت على وثائق API التفاعلية، في وقت لاحق وسوف تستخدم متصفح لعرض وتشغيل API الراحة لدينا.

التبختر Codegen: ويمكن تبسيط عملية بناء المعرفة من قبل أي API مواصفات لتوليد بذرة وSDK عميل ملقم هو OpenAPI (سابقا التبختر).

لماذا استخدام التبختر

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

تغيير الرمز تغيير المستند. كمية صغيرة فقط من الملاحظات، وثائق API التبختر يمكن تلقائيا استنادا إلى رمز، ضمانة جيدة جدا في الوقت المناسب من الوثيقة.

عبر اللغوي، ويدعم 40 لغة.

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

الوثائق أيضا يمكن استيراد قواعد أدوات (مثل SoapUI) ذات الصلة، فإن هذه الأدوات تلقائيا إنشاء الاختبار الآلي بالنسبة لنا.

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

مشروع جاهز الربيع التمهيد الويب

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

إنشاء مشروع الربيع التمهيد فارغة

يمكنك إنشاء صفحة فارغة قبل الربيع Initializr من مشروع الربيع التمهيد، بالطبع، يمكنك تحميل ملف springboot-pom.xml، ومن ثم استخدام مخضرم لبناء مشروع الربيع التمهيد. بعد إنشاء المشروع، وذلك لتسهيل إعداد مدونة خلفك يمكن استيرادها إلى IDE المفضلة لديك، وأنا اخترت هنا ذكاء IDEA مفتوحة.

إضافة تعتمد

منذ إنشاء مشروع ويب، لذلك نحن بحاجة إلى الاعتماد على مكونات الربيع التمهيد الويب، تحتاج فقط إلى إضافة ما يلي إلى pom.xml:

قائمة 1. إضافة الاعتماد الويب

< التبعية >

< groupId > org.springframework.boot < / GroupId >

< artifactId > الربيع التمهيد بداية على شبكة الإنترنت < / ArtifactId >

< / التبعية >

الكتابة واجهة

أولا نحن إنشاء ثلاث مجموعات: cn.itweknow.sbswagger.controller، cn.itweknow.sbswagger.testcontroller وcn.itweknow.sbswagger.model.

في حزمة UserController.java الدرجة تحكم جديدة، حزمة testcontroller الطبقة TestController.java جديدة، وفئة جديدة في حزمة نموذج User.java.

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

القائمة 2. كود UserController.java

RestController

RequestMapping ( "المستخدم /")

الطبقة العامة UserController {

PostMapping ( "/ إضافة")

addUser منطقية العام (RequestBody المستعمل العضو) {

عودة كاذبة.

}

GetMapping ( "/ اكتشاف / {معرف}")

العضو العام findById (PathVariable ( "ID") معرف كثافة العمليات) {

عودة العضو الجديد ()؛

}

PutMapping ( "تحديث /")

تحديث منطقية العام (RequestBody المستعمل العضو) {

العودة الحقيقية.

}

DeleteMapping ( "/ حذف / {معرف}")

العام منطقية حذف (PathVariable ( "ID") معرف كثافة العمليات) {

العودة الحقيقية.

}

}

Swagger2 المتكاملة

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

/ المستخدم / إضافة: المستخدمين الجدد.

/ المستخدم / بحث / {معرف}: معرف المستخدم الاستعلام.

/ المستخدم / تحديث: تحديثات المستخدم.

/ المستخدم / / حذف {معرف}: معرف المستخدم حذف.

/ اختبار / اختبار: واجهة الاختبار.

أدناه سوف نقوم من خلال دمج Swagger2، ومن ثم يولد تلقائيا وثائق واجهة لهذه الراحة API خمسة.

إضافة تعتمد

أول شيء فعله هو إضافة تبعيات الطبيعية الحاجة Swagger2:

قائمة 3. إضافة التبختر تعتمد

< التبعية >

< groupId > io.springfox < / GroupId >

< artifactId > springfox-swagger2 < / ArtifactId >

< نص > 2.9.2 < / النسخة >

< / التبعية >

التكوين جافا

يوفر Springfox يعترض المفكرة، حتى نتمكن من تكوين مرن للممتلكات التبختر. دعونا خلق فئة cn.itweknow.sbswagger.conf.SwaggerConfig.java جديدة، وإضافة ما يلي:

قائمة 4. التبختر تكوين جافا

Configuration

@ EnableSwagger2

الطبقة العامة SwaggerConfig {

Bean

الجمهور دوكت API () {

العودة المفكرة الجديدة (DocumentationType.SWAGGER_2)

. تحديد ()

.apis (RequestHandlerSelectors.any ())

.paths (PathSelectors.any ())

. البناء ()؛

}

}

ملاحظة:Configuration يقول حاجة الربيع التمهيد لتحميل الطبقة التكوين، @ EnableSwagger2 يتم تمكين Swagger2، إن لم يكن زيادة، فمن الطبيعي أنه لا يمكن أن نرى الجزء الخلفي من نتائج التحقق.

التحقق

حتى الآن، وقد نجحنا في الربيع بعد مشروع التمهيد يدمج Swagger2، بدء المشروع، ونحن يمكن الوصول إليها من خلال مستعرض إلى http: للتحقق من 8080 / V2 / المعهد، والمستندات، وستجد يتم إرجاع النتائج: // المضيف المحلي بعض سلسلة JSON، قراءة سيئة للغاية. لحسن الحظ توفر Swagger2 على SwaggerUI اجهة البصرية بالنسبة لنا، ونحن هنا نلقي المحاولة.

التبختر UI المتكاملة

إضافة تعتمد

كما كان من قبل، فإن الخطوة الأولى هي إضافة التبعية المتعلقة التكامل، إضافة التالية في pom.xml إلى:

قائمة 5. إضافة الاعتماد التبختر UI

< التبعية >

< groupId > io.springfox < / GroupId >

< artifactId > springfox-غرور-واجهة المستخدم < / ArtifactId >

< نص > 2.9.2 < / النسخة >

< / التبعية >

مصادقة الوصول

في الواقع، تحتاج فقط إلى إضافته الاعتماد على ذلك، فإننا إعادة تشغيل المشروع، ثم مستعرض إلى http: // المضيف المحلي: 8080 / اختيال-ui.html ترون تأثير ما يلي:

1. التبختر UI FIG.

اضغط للتكبير

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

التكوين المتقدم

الوثائق ذات الصلة التي تصف التكوين

عن طريق زيادة تحكمApi بناء على الشرح، وبطاقة المعلومات قد تضاف إلى وصف وحدة تحكم.

قائمة 6. إضافة وصف للمراقب

1

2

Api (العلامات = "واجهات المستخدم"، وصف = "الراحة API توفير المستخدم ذات الصلة")

الطبقة العامة UserController

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

قائمة 7. واجهة لإضافة معلومات وصفية

ApiOperation ( "الجديد واجهة المستخدم")

PostMapping ( "/ إضافة")

addUser منطقية العام (RequestBody المستعمل العضو) {

عودة كاذبة.

}

الوصف المادي، يمكن أن نأتي إلى كائنات API لدينا تشارك في وصف الشروح التي قدمهاApiModel وApiModelProperty.

قائمة 8. إضافة إلى وصف نوع كيان

ApiModel ( "كيان المستخدم")

فئة العمومي العضو {

ApiModelProperty ( "هوية المستخدم")

هوية الباحث الخاص؛

}

التكوين معلومات وثيقة، كما يدعم التبختر نسخة وضع بعض الوثائق، والاتصالات، والبريد الإلكتروني، على شبكة الإنترنت وحقوق المؤلف وبروتوكول مفتوحة المصدر وهكذا دواليك، ولكن قبل بضعة مختلفة هو أن لا يتم تكوين هذه المعلومات من خلال الملاحظات، ولكن عن طريق خلق الأجسام ApiInfo وباستخدام طريقة Docket.appInfo () لمجموعة، ويمكننا أن نضيف ما يلي في الصف SwaggerConfig.java.

قائمة 9. تكوين وثيقة معلومات

Bean

الجمهور دوكت API () {

العودة المفكرة الجديدة (DocumentationType.SWAGGER_2)

. تحديد ()

.apis (RequestHandlerSelectors.any ())

.paths (PathSelectors.any ())

. البناء ()

.apiInfo (apiInfo ())؛

}

خاصة ApiInfo apiInfo () {

العودة ApiInfo الجديدة (

"وثيقة المثال الربيع التمهيد مشروع التكامل التبختر"

"موقع بلوق بلدي: الشبكي: //itweknow.cn، مرحبا بكم في الزيارة"،

"V1.0 API"،

"شروط الخدمة"،

جديد الاتصال ( "ليست مثل اسم جيدة"، "https://itweknow.cn"، "gancy.programmer@gmail.com")،

"أباتشي"، " Collections.emptyList ())؛

}

بعد الخطوات المذكورة أعلاه، وثائقنا تصبح مثل الشكل التالي، والآن يبدو واضحا من ذلك بكثير.

الشكل 2. التبختر ملء كامل المعلومات واجهة مستندات

اضغط للتكبير

مرشح واجهة

أحيانا نحن لا نريد يتم تقديم جميع API الراحة في الوثيقة، في هذه الحالة Swagger2 توفر لنا وسيلة للدلالة على اثنين من تكوينات، واحدة على أساس الملاحظاتApiIgnore، والآخر هو زيادة الفرز على المفكرة.

ApiIgnore تعليق.

إذا كنت ترغب في حذف حماية واجهة المستخدم (المستخدم / حذف) في الوثيقة، فإنك تحتاج فقط إلى إضافةApiIgnore على إزالة المستخدمين.

مثال 10.ApiIgnore قائمة

1

2

ApiIgnore

الجمهور منطقية حذف (PathVariable ( "ID") كثافة العمليات معرف)

فحص زيادة في المفكرة. توفر الطبقة المفكرة واجهات برمجة التطبيقات () ومسارات () طريقتين لمساعدة لنا تصفية الواجهات على مستويات مختلفة:

• واجهات برمجة التطبيقات (): في هذه الطريقة يمكننا تحديد اسم الحزمة، والذي يسمح التبختر فقط لبعض حزم مسح أدناه.
• مسارات (): في هذه الطريقة قد تتم تصفيته عن طريق فحص عنوان الموقع API.

في الأقسام Swagger2 متكاملة بعثنا يتم فحص هذه الأساليب اثنين من كل، لم تحدد أي معايير الترشيح. إذا كان لنا أن تحديد الكائن المفكرة قبل أن تعديل واجهات برمجة التطبيقات () طريقة والمسارات () الأسلوب هو ما يلي، ثم وثائق واجهة سيعرض فقط / المستخدم / إضافة و / المستخدم / العثور على / {معرف} واجهات اثنين.

قائمة 11. عن طريق تكوين واجهة المفكرة فحص

.apis (RequestHandlerSelectors.basePackage ( "cn.itweknow.sbswagger.controller"))

.paths (Predicates.or (PathSelectors.ant ( "/ المستخدم / إضافة")،

PathSelectors.ant ( "/ المستخدم / العثور على / *")))

الرقم 3. بعد التبختر بعد اجهة ثيقة فحص

اضغط للتكبير

مخصص استجابة رسالة

اختيال يتيح لنا () طرق للاستجابة تغطية طريقة رسالة HTTP العالمي globalResponseMessage المفكرة، ولكن علينا أولا أن أقول من خلال useDefaultResponseMessages طريقة المفكرة من التبختر عدم استخدام رسالة استجابة HTTP الافتراضي، على افتراض 500 و 403 أخطاء نحن بحاجة لتغطية كل طريقة على GET رسالة ردا على ذلك، إضافة المحتويات التالية ونحن بحاجة فقط دوكت فول في الصف SwaggerConfig.java:

قائمة 12. مخصص استجابة رسالة

بعد إضافة رمز أعلاه كما هو مبين أدناه، وسوف تجد عرض الصفحة SwaggerUI جميع أنواع طلبات GET 403 و 500 رسالة استجابة خطأ أصبحت محتوى عادتنا.

4. رسالة استجابة مخصص من FIG.

استخدام التبختر UI

عرض واجهة

سوف SwaggerUI تظهر وسيلة لمسح قائمة بجميع واجهات، والحالة الأولية آخذة في التقلص، ونحن بحاجة فقط إلى انقر فوق لتوسيع بما فيه الكفاية، ولكن الطريقة التي طلب يحدد واجهة على اليسار (GET، POST و PUT، DELETE، وهلم جرا).

قائمة ميناء FIG 5. التبختر

اضغط للتكبير

المكالمات واجهة

كما هو مبين أدناه، اضغط على الزاوية اليمنى العليا من واجهة بعد بداية الصفحة جربه  زر واحدة، الصفحة سوف تصبح كما هو مبين:

الشكل 6. واجهة واجهة تفاصيل

اضغط للتكبير

SwaggerUI تعطينا الإكمال التلقائي المعلمات بنية طلب البيانات، يتعين علينا القيام به هو النقر نفذ  يمكنك إجراء المكالمات

الرقم 7. واجهة الدعوة واجهة

اضغط للتكبير

نموذج

كما هو مبين أدناه، سيتم استخدام SwaggerUI لديناApiModel الكيانات الشروح وصفها في الملاحظات والشروح إلى كياناتApiModelProperty تجديد تلقائيا وصفاتهم.

FIG كيان واجهة 8.

اضغط للتكبير

الإيضاحات ذات الصلة

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

الملاحظات المتعلقة تحكم

يمكن تقديم وصف للتحكم:Api.

الجدول 1. السمات الرئيسيةApi

الشرح نوع العقار الوصف tagsString العلامة تحكم. descriptionString وصف المراقب المالي (ورد هذا المجال أن تنتهي).

تعليق حول واجهة

ApiOperation: يمكن تقديم وصف واجهة.

الجدول سمات 2.ApiOperation الرئيسية

الشرح نوع العقار الوصف valueString مواصفات واجهة. ملاحظات الإصدار واجهة notesString. tagsStirng العلامة. responseClass < ؟ > واجهة نوع الإرجاع. httpMethodString اجهة وضع الطلب.

لم يكن لديك وثيقة التبختر واجهة عرض الشرح:ApiIgnore.

ApiImplicitParams: وصف واجهة لغير المستهدفة مجموعة المعلمة.

ApiImplicitParam: وصف المعلمة غير كائن واجهة يستخدم عادة في تركيبة معApiImplicitParams.

الجدول 3.ApiImplicitParam الرئيسي سمات

شرح خصائص الوصف نوع paramType من معلمات الاستعلام، المعلمة هي في الواقع هناك. القيمة:

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

معلمة نوع البيانات نوع البيانات. القيمة:

• طويل
• سلسلة

تسمية اسم المعلمة. المعلمة شعور الوصف القيمة. مطلوب إذا لزم الأمر. القيمة:

• صحيح: المعلمة المطلوبة.
• كاذبة: المعلمات الاختيارية.

الملاحظات المتعلقة نموذج

ApiModel: يمكن تقديم وصف للمؤسسات ذات العلاقة واجهة.

ApiModelProperty: الوصف قد يكون خصائص الكيان التخلص منها.

الجدول 4.ApiModelProperty الرئيسي سمات

الشرح نوع العقار الوصف valueString الوصف المجال. nameString اسم الحقل إعادة كتابة. dataTypeStirng كتابة نوع الحقل. سواء requiredboolean المطلوبة. مثال exampleStirng. سواء اخفاء hiddenboolean مجال في الوثيقة. allowEmptyValueboolean ما اذا كان سيسمح فارغة. allowableValuesString هذا الحقل يسمح قيمة المعلمة عندما API لدينا هو نوع سردي، واستخدام هذه السمة يمكن أن أقول لكم بوضوح المستخدم من API يمكن أن تسمح قيمة المعلمة واردة.

استنتاج

في هذا البرنامج التعليمي، تعلمنا كيفية استخدام التبختر 2 لتوليد وثائق API الربيع التمهيد REST. درسنا أيضا كيفية API التصفية، رسالة استجابة HTTP مخصصة وكيفية استخدام SwaggerUI الاتصال مباشرة API لدينا. يمكنك العثور على الإعمال الكامل لهذا البرنامج التعليمي على جيثب، الذي يقوم على أساس مشروع IDEA IntelliJ لل، لذلك ينبغي أن يكون من السهل استيراد والتشغيل.