Fosrestbundle: إنشاء وثائق REST API خارج المسارات

تحقق من http://getfrapi.com/ screencast للحصول على بعض الإلهام.

لقد رأيت ذلك بالفعل. لكني لا أحب أشياء كثيرة في إدراكها. بادئ ذي بدء ، REST ليست مريحة :- D.

"إلهام" ولم أتحدث عن راحتهم ولكن عن جيل المستندات (والاختبار) :)

أنا شخصياً لا أحب ذلك ، لكن هل يمكننا مناقشة إنشاء الوثائق بتنسيق WADL؟

http://www.w3.org/Submission/wadl/

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

هل نتحدث عن توثيق للعملاء؟

ضع في اعتبارك ، هذا ما تحاول REST تجنبه :)

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

أيضًا موضوع آخر يجب تجاهله: بعض العملاء يحبون قتل الأشجار تمامًا ومن الجيد ألا تضطر إلى إضاعة الكثير من الوقت في ملء هذه الصفحات الورقية :)

توافق ، الشيء الوحيد الذي يجب تجنبه هو الاعتماد بشكل كبير على الوثائق التي تم إنشاؤها ، وإلا فسنكرر WSDL

رفض لقتلة الأشجار :)

بقدر ما أعرف ، فإن مستندات REST API الحقيقية تدور حول تحديد أنواع الوسائط وعلاقاتها ، وليس عناوين URL. على سبيل المثال http://kenai.com/projects/suncloudapis/pages/Home ، http://amundsen.com/media-types/collection/

ولكن بالنسبة لواجهات برمجة تطبيقات HTTP البسيطة ، وهو ما سيكون عليه الحال بالنسبة لـ 80٪ من مشاريع الويب ، ستظل هذه الميزة مفيدة.

نعم فلادار ، من الواضح أن قوالب URI شريرة. ولكن إذا احتجنا إلى تطوير حزمة REST ، فيجب علينا اتباع هذه المبادئ.

يتناسب قالب URI جيدًا مع ApiBundle

قد يكون قادرًا على أخذ المفاهيم من http://swagger.wordnik.com/

: +1: إلى Swagger. هذا يبدو رائعا!

لإنشاء تجربة مماثلة ، قد نتمكن من:

• تم تمييز طرق التحليل كـ @apidoc أو شيء من هذا القبيل
• احصل على وصف للطريقة والمعلمات من docblock على الطرق المميزة بعلامات @apidoc
• السماح للاختبار المضمن للمكالمات على أساس كل إجراء.

بشكل عام ، أعتقد أن الحصول على شاشات مثل Swagger أمر ممكن جدًا ويعطي الكثير من المعنى لهذه الحزمة.

هناك خيار آخر يتمثل في إنشاء JSON الذي يستهلكه Swagger ولكنه يأتي مع بعض الوزن (Java) ... تفضل رؤية تطبيق "like".

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

pminnieur يبدو أنه يمكننا بسهولة توفير نفس الوظائف الأساسية بدلاً من الدمج.

على الأقل يمكن أن تعمل مثل https://github.com/FriendsOfSymfony/FOSJsRoutingBundle - فقط إضافة بعض HTML / CSS الهائل وكشف مسارات RESTful الخاصة بك مع نوع من مستندات API. ربما يمكننا استخدام بعض التعليقات التوضيحية لدعم المزيد من المعلومات.

أود أن أبدأ بهذا ولكن أعتقد أنه سيكون من الأفضل وضع الكود في حزمة مخصصة (مثل FOSRestAPIExplorerBundle). السؤال هو ، هل يجب أن ندعم Swagger API فقط (لذلك يتم استخدام Swagger لتصور المعلومات التي تم جمعها وعرضها في JSON) أم يجب علينا توفير واجهة الويب الخاصة بنا أيضًا؟

تبدو الحزمة المنفصلة فكرة جيدة. إذا كنا ندعم اختياراتنا فقط ، فقد نرغب في ذكر ذلك في اسم الحزمة. لا أعرف ما إذا كنا نريد أيضًا دعم شيء آخر. يعتمد على دوافعك ونوعية التباهي. سؤال واحد حول اختيال: كيف يعمل ذلك مع واجهات برمجة التطبيقات الداخلية التي لا يريد المرء أن يعرضها لخدمة خارجية؟

أعتقد أنه يتعين عليك ببساطة عدم جعل عنوان URL يعيد Swagger JSON للجمهور إذا كنت لا تريد أن يكون عامًا ...: D بجدية ، أود استخدام التعليقات التوضيحية وإذا كنت لا تريد أن يكون المسار عام ، لن تضيف التعليق التوضيحي @Expose() أو تضيف @Expose(false) - شيء من هذا القبيل. تمامًا مثل FOSJsRoutingBundle ، يمكن تكوين كيفية التعامل معه (كشف كل شيء افتراضيًا ، أو كشف القائمة البيضاء). إذا كنت تقصد "هذا رابط لواجهة برمجة التطبيقات العامة وهذا الرابط مخصص لك فقط" ، فقد نضيف تعليقًا توضيحيًا مثل @Api("public") و @Api("private") بما في ذلك مكون الأمان حتى تتمكن من توزيع واجهة برمجة تطبيقات مختلفة وثائق لأشخاص مختلفين (والتحكم في الوصول إلى 'em).

بالنسبة للاسم: أرغب في الحصول على اسم عام ، ستكون Swagger أول خدمة توثيق لواجهة برمجة التطبيقات يتم دعمها. إذا أراد الأشخاص إضافة أي خدمة أخرى ، فيمكنهم فعل ذلك فقط (ويجب ألا يبدأوا من نقطة الصفر). odino على سبيل المثال يمكن أن تضيف دعم WADL. على الأقل أود تقديم واجهة ويب أيضًا.

لقد أنشأت مستودع GitHub حتى الآن لجمع الأفكار والقضايا قبل أن نبدأ. لا تتردد في فتح مشكلات لأية أسئلة أو مواضيع للمناقشة (يمكن مناقشة التسمية أيضًا ، بالتأكيد) ؛-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

حسنا جيد. بمجرد تشكيل الأشياء .. يمكننا نقلها إلى FOS

هل تخطط للاستفادة من https://github.com/wordnik/swagger-ui باعتباره "جهاز العرض"؟

في المقام الأول ، نعم. قم فقط بإنشاء ملف json متوافق مع مواصفات swagger ليتم استخدامه بواسطة swagger-ui.

إغلاق لصالح https://github.com/nelmio/NelmioApiDocBundle

أعلم أن هذا قديم جدًا ، لكن بعض الأشياء تغيرت منذ ذلك الحين ووجدت هذا سريعًا نسبيًا أثناء البحث عن حزمة / حزمة لـ Swagger / Openapi.
أي فرصة لإعادة النظر في هذا؟ نظرًا لأنه تم التخلي عن NelmioApiDocBundle ولا يمكنني رؤية أي بديل حقيقي يتكامل مع Symfony لـ Swagger / OpenApi (أو أي برنامج آخر حقًا ، RAML ، ...؟).