توليد ملفات Swagger

نظرة عامة

كما نعلم، يوفر إطار العمل beego دعمًا لتوليد ملفات swagger لتوضيح الواجهة البرمجية للتطبيقات API عبر أداة سطر الأوامر المسماة "bee". Casdoor مبني أيضًا على أساس beego. ومع ذلك، وجدنا أن الملفات swagger التي تم توليدها بواسطة bee فشلت في تصنيف الواجهات البرمجية للتطبيقات APIs مع تسمية "@Tag". لذا، قمنا بتعديل bee الأصلي لتنفيذ هذه الوظيفة.

كيفية كتابة التعليق

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

// @Title Login
// @Tag Login API
// @Description login
// @Param   oAuthParams     query    string  true        "oAuth parameters"
// @Param   body    body   RequestForm  true        "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

الواجهات البرمجية للتطبيقات APIs التي تحمل نفس تسميات "@Tag" سيتم وضعها في نفس المجموعة.

كيفية توليد ملف swagger

0. اكتب التعليقات للواجهة البرمجية للتطبيقات API بالتنسيق الصحيح.

1. احصل على هذا المستودع: https://github.com/casbin/bee.

2. قم ببناء bee المعدل. على سبيل المثال، في الدليل الجذر لـ casbin/bee، قم بتشغيل الأمر التالي:

   go build -o mybee .

3. انسخ mybee إلى الدليل الأساسي لـ casdoor.

4. في ذلك الدليل، قم بتشغيل الأمر التالي:

   mybee generate docs

5. (اختياري) إذا كنت ترغب في توليد وثيقة swagger لتسميات أو واجهات برمجية للتطبيقات محددة، إليك بعض الأوامر المثالية:

   mybee generate docs --tags "Adapter API"
   mybee generate docs --tags "Adapter API,Login API"
   mybee generate docs --apis "add-adapter"
   mybee generate docs --apis "add-adapter,delete-adapter"

   ملاحظة: نحن نقبل فقط الفاصلة , كمفرق عند توفير علامات/واجهات برمجية للتطبيقات متعددة.

ثم ستجد أن الملفات الجديدة swagger تم توليدها.