springdoc openapi

هام: springdoc-openapi v1.8.0 هو أحدث إصدار مفتوح المصدر يدعم Spring Boot 2.x و1.x.

يتوفر الآن دعم موسع لمشروع Springdoc-openapi v1 للمؤسسات التي تحتاج إلى دعم بعد عام 2023.

لمزيد من التفاصيل، لا تتردد في التواصل معنا: [email protected]

springdoc-openapi موجود في Open Collective. إذا كنت ❤️ هذا المشروع فكر في أن تصبح راعيًا.

هذا المشروع برعاية

جدول المحتويات

• التوثيق الكامل
• مقدمة
• ابدء
  • مكتبة لتكامل Springdoc-openapi مع Spring-Boot وSwagger-UI
  • التمهيد الربيعي مع تطبيقات OpenAPI التجريبية.
    • كود المصدر للتطبيقات التجريبية.
    • عرض Spring Boot 2 Web MVC مع OpenAPI 3.
    • عرض Spring Boot 2 WebFlux مع OpenAPI 3.
    • العرض التوضيحي Spring Boot 2 WebFlux مع نقاط النهاية الوظيفية OpenAPI 3.
    • العرض التوضيحي لـ Spring Boot 2 وSpring Hateoas مع OpenAPI 3.
  • تكامل المكتبة في مشروع Spring Boot 3.x بدون واجهة مستخدم swagger:
  • معالجة الأخطاء لـ REST باستخدام @ControllerAdvice
  • إضافة معلومات API ووثائق الأمان
  • دعم Spring-webflux مع وحدات التحكم المشروحة
• شكر وتقدير
  • المساهمين
  • دعم إضافي

التوثيق الكامل

مقدمة

تساعد مكتبة Springdoc-openapi Java في أتمتة إنشاء وثائق API باستخدام مشاريع Spring Boot. يعمل Springdoc-openapi من خلال فحص التطبيق في وقت التشغيل لاستنتاج دلالات واجهة برمجة التطبيقات (API) استنادًا إلى تكوينات Spring وبنية الفئة والتعليقات التوضيحية المتنوعة.

تقوم المكتبة تلقائيًا بإنشاء الوثائق في صفحات بتنسيق JSON/YAML وHTML. يمكن استكمال الوثائق التي تم إنشاؤها باستخدام التعليقات التوضيحية swagger-api .

تدعم هذه المكتبة:

• واجهة برمجة التطبيقات المفتوحة 3
• Spring-boot v3 (Java 17 وJakarta EE 9)
• JSR-303، خصيصًا لـ @NotNull و@Min و@Max و@Size.
• اختيال واجهة المستخدم
• أوث 2
• الصور الأصلية لـ GraalVM

والفيديو التالي تعريفي بالمكتبة:

• https://youtu.be/utRxyPfFlDw

للحصول على دعم Spring-boot v3 ، تأكد من استخدام Springdoc-openapi v2

هذا مشروع مجتمعي، ولا تتم صيانته من قبل المساهمين في إطار عمل الربيع (المحوريون)

ابدء

مكتبة لتكامل Springdoc-openapi مع Spring-Boot وSwagger-UI

• ينشر swagger-ui تلقائيًا في تطبيق Spring Boot 3.x
• ستكون الوثائق متاحة بتنسيق HTML، باستخدام الجرار الرسمية لواجهة المستخدم.
• يجب أن تكون صفحة Swagger UI متاحة بعد ذلك على http://server: port/context-path/swagger-ui.html وسيكون وصف OpenAPI متاحًا على عنوان url التالي لتنسيق json: http://server:port/context -path/v3/api-docs
  • server : اسم الخادم أو IP
  • port : منفذ الخادم
  • context-path : مسار سياق التطبيق
• يمكن أن تكون الوثائق متاحة أيضًا بتنسيق yaml، على المسار التالي: /v3/api-docs.yaml
• أضف مكتبة springdoc-openapi-ui إلى قائمة تبعيات مشروعك (لا حاجة إلى تكوين إضافي):

مخضرم

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

جرادل

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• هذه الخطوة اختيارية: للحصول على مسار مخصص لوثائق التباهي بتنسيق HTML، قم بإضافة خاصية Springdoc مخصصة، في ملف تكوين التشغيل الربيعي الخاص بك:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

التمهيد الربيعي مع تطبيقات OpenAPI التجريبية.

كود المصدر للتطبيقات التجريبية.

عرض Spring Boot 3 Web MVC مع OpenAPI 3.

عرض Spring Boot 3 WebFlux مع OpenAPI 3.

العرض التوضيحي Spring Boot 3 WebFlux مع نقاط النهاية الوظيفية OpenAPI 3.

العرض التجريبي لـ Spring Boot 3 وSpring Cloud Function Web MVC.

العرض التجريبي لـ Spring Boot 3 ووظيفة Spring Cloud WebFlux.

العرض التجريبي لـ Spring Boot 3 وSpring Cloud Gateway.

تكامل المكتبة في مشروع Spring Boot 3.x بدون واجهة مستخدم swagger:

• ستكون الوثائق متاحة على عنوان url التالي لتنسيق json: http://server: port/context-path/v3/api-docs
  • server : اسم الخادم أو IP
  • port : منفذ الخادم
  • context-path : مسار سياق التطبيق
• ستكون الوثائق متاحة أيضًا بتنسيق yaml، على المسار التالي: /v3/api-docs.yaml
• أضف المكتبة إلى قائمة تبعيات مشروعك. (ليس هناك حاجة إلى تكوين إضافي)

مخضرم

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

جرادل

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• هذه الخطوة اختيارية: للحصول على مسار مخصص لوثائق OpenAPI بتنسيق Json، قم بإضافة خاصية Springdoc مخصصة، في ملف تكوين التشغيل الربيعي الخاص بك:

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• هذه الخطوة اختيارية: إذا كنت تريد تعطيل نقاط نهاية springdoc-openapi ، أضف خاصية Springdoc مخصصة، في ملف تكوين spring-boot الخاص بك:

 # disable api-docs
springdoc.api-docs.enabled =false

معالجة الأخطاء لـ REST باستخدام @ControllerAdvice

لإنشاء الوثائق تلقائيًا، تأكد من أن جميع الطرق تعلن عن استجابات رمز HTTP باستخدام التعليق التوضيحي: @ResponseStatus.

إضافة معلومات API ووثائق الأمان

تستخدم المكتبة الحزم التي تم تكوينها تلقائيًا لتطبيق Spring-Boot للبحث عن التعليقات التوضيحية التالية في Spring Beans: OpenAPIDefinition وInfo. تعلن هذه التعليقات التوضيحية عن معلومات واجهة برمجة التطبيقات: العنوان والإصدار والترخيص والأمان والخوادم والعلامات والأمان والمستندات الخارجية. للحصول على أداء أفضل لإنشاء الوثائق، قم بتعريف التعليقات التوضيحية @OpenAPIDefinition و @SecurityScheme داخل إحدى وحدات الفول المُدارة بواسطة Spring.

دعم Spring-webflux مع وحدات التحكم المشروحة

• يمكن أن تكون الوثائق متاحة أيضًا بتنسيق yaml، على المسار التالي: /v3/api-docs.yaml
• أضف المكتبة إلى قائمة تبعيات مشروعك (ليس هناك حاجة إلى تكوين إضافي)

مخضرم

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

جرادل

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• هذه الخطوة اختيارية: للحصول على مسار مخصص لوثائق التباهي بتنسيق HTML، قم بإضافة خاصية Springdoc مخصصة، في ملف تكوين التشغيل الربيعي الخاص بك:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

تتم استضافة مكتبات springdoc-openapi في المستودع المركزي المخضرم. يمكن الاطلاع على القطع الأثرية والوصول إليها في المواقع التالية:

الإصدارات:

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/ .

لقطات:

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/ .

شكر وتقدير

المساهمين

Springdoc-openapi ذو صلة ويتم تحديثه بانتظام نظرًا للمساهمات القيمة من المساهمين فيه.

شكرا لكم جميعا على دعمكم!

دعم إضافي

• فريق الربيع - نشكرهم على دعمهم من خلال مشاركة جميع الموارد ذات الصلة بمشاريع الربيع.
• JetBrains - شكرًا جزيلاً لدعم مشروع Springdoc-openapi.