كيفية تغيير مسار URL الافتراضي لواجهة سوغر

Swagger UI هي أداة رائعة لتصور والتفاعل مع مواصفات OpenAPI. أثناء عملك مع Swagger UI، ستلاحظ أن عناوين URL تلعب دورًا مهمًا في تكوين والوصول إلى وثائق API. في هذه التدوينة، سنوضح لك عناوين URL الخاصة بـ Swagger UI لمساعدتك في استخدامها بشكل أكثر فعالية.

ما هو Swagger UI؟

Swagger UI هي أداة تتيح للمستخدم التفاعل مع APIs باستخدام وثائق مواصفات OpenAPI. تقرأ وثيقة المواصفة وتعرضها في تنسيق تفاعلي بصري. يساعد هذا المطورين على فهم APIs، وإرسال طلبات اختبار، وتصحيح الأخطاء، واستخدام APIs الخاصة بك.

يتوافق عنوان URL الخاص بـ Swagger UI مع نقطة النهاية حيث تخدم ملف JSON الخاص بمواصفات OpenAPI. هذا يعني أنك تحتاج إلى تقديم عنوان ويب يشير إلى موقع ملف JSON الخاص بـ OpenAPI. يقرأ Swagger UI هذا الملف لإنشاء واجهة سهلة الاستخدام يمكن الوصول إليها من خلال ذلك الرابط. قد يختلف الهيكل الدقيق لعنوان URL بسبب اختلاف تكوينات الخادم.

ميزات Swagger UI

Swagger UI هي أداة قوية تقدم مجموعة من الميزات لاختبار وفهم وتصور APIs. يتم ذكر بعض الميزات أدناه:

تشمل الميزات الرئيسية:

• الاختبار المباشر لـ APIs مباشرة داخل الوثائق
• تحكم بديهي لمعلمات الطلب
• توليد قصاصات من الشيفرة لاستدعاءات API
• دعم Markdown للتنسيق
• أدوات للتعاون بين الفرق
• عرض تلقائي لنماذج البيانات
• تنظيم ونطاق نقاط نهاية API

معلمات URL الخاصة بـ Swagger UI

لدى Swagger UI معلمات مختلفة في عنوان URL لتكوين سلوكها ومظهرها. تؤثر هذه على كيفية عرض وثائق API باستخدام Swagger UI. بعض من أكثر معلمات URL المستخدمة شيوعًا هي:

URL:

هذا يحدد عنوان URL لملف مواصفات OpenAPI الذي يجب أن يستخدمه Swagger UI لتوليد وثائق API. الشكل الخاص بالـ URL هو كما يلي:

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json

ConfigUrl:

configUrl يوفر عنوان URL لتكوين JSON يقوم بتخصيص وتعديل سلوك Swagger UI.

http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json

deepLinking:

يتيح الرابط العميق إلى العمليات الفردية أو العلامات في وثائق API. إنه مفيد عند مشاركة روابط مباشرة لأجزاء معينة من الوثائق.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true

oauth2RedirectUrl:

يتيح للمستخدمين إعادة التوجيه إلى عنوان URL آخر بعد المصادقة الناجحة عندما تتطلب واجهتك API مصادقة OAuth 2.0.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect

defaultModelsExpandDepth:

يعدّل العمق الافتراضي للنماذج في الوثائق.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2

كيفية العثور على عنوان URL لـ Swagger UI

بعض الأشخاص مرتبكون بشأن مكان URL الخاص بـ Swagger UI. يتم إنشاؤه استنادًا إلى تكوين مشروعك. للعثور على عنوان URL، اتبع هذه الخطوات:

1. تأكد من تكوين مشروعك لإنشاء وثائق Swagger.
2. للوصول إلى Swagger UI، تحتاج إلى دمج عنوان URL الأساسي لواجهة API الخاصة بك مع نقطة نهاية وثائق Swagger. سينتج عن ذلك عنوان URL الخاص بـ Swagger UI.

على سبيل المثال، إذا كنت تستضيف واجهة API الخاصة بك على http://localhost:3000 ونقطة النهاية الخاصة بك هي /swagger-ui/، فسوف يصبح عنوان URL الخاص بك http://localhost:8080/swagger-ui/.

إذا كنت لا تزال تواجه صعوبة في العثور على عنوان URL الخاص بـ Swagger UI، يمكنك الرجوع إلى وثائق الإطار أو المكتبة التي تستخدمها لإنشاء APIs الخاصة بك. سيساعدك ذلك في توفير معلومات حول كيفية الوصول إلى عنوان URL لإعدادك المحدد.

كيفية تغيير مسار Defauth الخاص بـ Swagger UI؟

يعتمد المسار الافتراضي لـ Swagger UI على تكوينات الخادم الخاص بك. يتم بناءه استنادًا إلى الموقع وأين قمت بنشر Swagger UI. يمكن تغيير المسارات الافتراضية لعناوين URL وفقًا لمتطلبات المستخدم والنشر. يجب أن تشير معلمة URL في عنوان URL إلى موقع ملف مواصفات OpenAPI.

هناك العديد من الطرق لتغيير المسار الافتراضي لعنوان URL لـ Swagger UI.

تغيير ملف تكوين Swagger (Apache وNginx):

إذا كنت تستخدم خادم ويب، يمكنك تغيير تكوينات الخادم الخاص بك للتعامل مع الطلبات على عنوان URL محدد.

Apache:

في حالة Apache، يمكنك تعديل ملف التكوين الخاص بك لإنشاء قاعدة إعادة كتابة بحيث يمكن إعادة توجيه الطلبات إلى مسار Swagger UI الخاص بك. يجب عليك فتح ملف التكوين الخاص بك، وغالبًا ما يُسمى ‘httpd.conf’ أو ‘apache2.conf’. أضف قاعدة إعادة الكتابة الخاصة بك للمسار المطلوب في هذا الملف.

RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]

يمكنك إعادة تشغيل خادم Apache الخاص بك حتى تنعكس التغييرات.

Nginx:

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

server {
    listen 80;
    server_name your-domain.com;

    location /api-docs {
        alias /path/to/your/swagger-ui;
        index index.html;
    }
}

تحقق من أي أخطاء في التركيب بعد إجراء التغييرات وقم بإعادة تحميل Nginx حتى تنعكس التغييرات.

استخدام أطر العمل مثل Express.js:

باستخدام Express.js، يمكنك تكوين مساراتك للتعامل مع طلبات Swagger UI.

لخدمة Swagger UI، يجب عليك تعريف مسار في ملف خادم Express.js الخاص بك.

const express = require('express');
const app = express();

app.use('/custom-path', express.static('swagger-ui'));

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

سيسمح لك ذلك بالوصول إلى Swagger UI الخاص بك على ‘custom-path’.

استغلال Springboot لتغيير المسار الافتراضي:

في تطبيق Spring Boot، يمكنك تعديل ملفات ‘application.properties’ أو ‘application.yml’. يمكنك إضافة الخاصية التالية لتغيير المسار الافتراضي لـ Swagger UI في ملفات ‘application.properties’ أو ‘application.yml’.

springfox.documentation.swagger-ui.path=/custom-path

يمكنك استبدال ‘/custom-path’ وفقًا لمسارك المطلوب.

بعد ذلك، تحتاج إلى تكوين Bean لتخصيص المسار. يمكنك تمديد ‘WebMvcConfigurerAdapter’ لتحقيق ذلك.

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
    }
}

تأكد من أن لديك التبعيات المطلوبة في Swagger لتحقيق هذه النتائج.

ثم تحتاج إلى تكوين الفئة الرئيسية لتطبيقك.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.package.name"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("توثيق API الخاص بك")
                .version("1.0")
                .build();
    }
}

استبدل “your.package.name” مع حزمة الأساس الخاصة بالتحكم لديك.

تهيئة Swagger UI:

يمكنك تعديل معلمة ‘url’ لتعكس مسار URL المطلوب. سيسمح لك ذلك بتغيير المسار الافتراضي لـ Swagger UI. عند تهيئة Swagger UI في JavaScript، يمكنك إجراء التغييرات التالية.

const ui = SwaggerUIBundle({
  url: "/custom-path/swagger.json", 
});

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

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

يمكنك استكشاف عدة طرق HTTP/HTTPS مثل POST وGET وPUT، إلخ.

يمكنك النقر على أي طريقة واستكشافها. إذا نقرت على طريقة POST، سترى خيارًا لتحميل صورة وتحديث معلمات الطريقة. يمكنك الضغط على ‘تنفيذ’، وسيتم تنفيذ طلبك.

يمكنك رؤية استجابة طلب POST عن طريق التمرير إلى الأسفل.

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

اعتبر Apidog لوثائق API أكثر قوة تفوق قدرات Swagger UI. يتيح Apidog إدارة دورة حياة API بالكامل بما في ذلك التصميم، والمحاكاة، والاختبار، والإصدارات، والتعاون والمزيد.

مع ميزات متقدمة مثل تكامل CI/CD وتدفقات العمل بين الفرق، يقدم Apidog مجموعة أدوات أكثر اكتمالاً لتبسيط تقديم API. منصته الشاملة تزيد من تطوير API وتحسن الإنتاجية.

استكشاف الأخطاء وإصلاحها لـ Swagger UI على localhost

إذا واجهت مشكلات مع عنوان URL الخاص بـ Swagger UI على localhost، هناك عدة خطوات لاستكشاف الأخطاء يمكنك النظر فيها لتشخيص المشكلة وحلها.

1. تأكد من تشغيل خادم API الخاص بك. لا يمكن لـ Swagger UI جلب الوثائق إذا كان خادمك يواجه صعوبة في التشغيل.
2. تحقق من تكوينات Swagger الخاصة بك لمعرفة ما إذا كانت معدة بشكل صحيح.
3. استخدم عنوان URL الصحيح لـ Swagger UI مع نقاط النهاية الصحيحة.
4. امسح ذاكرة التخزين المؤقت لمتصفحك. أحيانًا، يمكن أن تحدث أخطاء غير متوقعة مع بيانات مخزنة.
5. أعد تشغيل كل من خادم API ومتصفحك بعد إجراء أي تغييرات.
6. تحقق مرة أخرى من صيغة عنوان URL الذي تستخدمه للوصول إلى Swagger UI.

الخاتمة

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

بينما يحتوي Swagger UI على مزاياه، هناك أيضًا العديد من القيود التي يمكن أن يراها المستخدم أثناء اختبار APIs. يوفر تعاونًا محدودًا بين المطورين ولا يدعم التكامل مع أدوات إدارة API الأخرى.