توليد Swagger/OpenAPI لـ Swift (iOS/macOS)

توليد Swagger/OpenAPI لـ Swift (iOS/macOS): نظرة شاملة على الأدوات

غالبًا ما يتطلب تطوير تطبيقات الأجهزة المحمولة لنظامي iOS/macOS التكامل مع REST API. كتابة طبقة الشبكة يدويًا هي عملية شاقة وعرضة للأخطاء، خاصة مع التغييرات المتكررة في المواصفات. الحل هو توليد كود Swift من مواصفات OpenAPI (المعروفة سابقًا باسم Swagger). في هذه المقالة، سنستعرض الأدوات الرئيسية وإمكانياتها وأمثلة على استخدامها.

ما هو OpenAPI ولماذا يحتاجه مطور Swift؟

OpenAPI هو معيار لوصف REST API بتنسيق YAML أو JSON. يحتوي على معلومات حول جميع نقاط النهاية (endpoints) والمعاملات ونماذج البيانات ورموز الاستجابة. يتيح توليد الكود من هذا الوصف ما يلي:

إنشاء نماذج بيانات محددة الأنواع تلقائيًا (struct, enum)
توليد عملاء API آمنين بعناوين URL وطرق HTTP صحيحة
تجنب الأخطاء المطبعية والتناقضات بين التوثيق والكود
توفير ساعات من العمل الروتيني عند تحديثات API

الأدوات الرئيسية لتوليد Swift

حاليًا، هناك ثلاثة أساليب شائعة:

1. Apollo iOS

Apollo هو عميل GraphQL قوي، لكن أدواته تدعم أيضًا OpenAPI من خلال الإضافة apollo-ios-openapi. ومع ذلك، فإن هذا الحل موجه أكثر نحو GraphQL، لذا بالنسبة لـ REST الخالص، من الأفضل النظر في خيارات أخرى.

2. CreateAPI

CreateAPI هو مولد حديث مكتوب بلغة Swift. يدعم OpenAPI 3.0 و 3.1، ويولد كود Swift نظيف باستخدام async/await أو Combine أو واجهات برمجة التطبيقات القائمة على closure. هذا هو الخيار الأفضل للمشاريع الجديدة.

3. Swagger Codegen / OpenAPI Generator

حلول كلاسيكية من المجتمع. تدعم العديد من اللغات، بما في ذلك Swift 5. يتم التوليد عبر CLI أو إضافات لـ Gradle/Maven. النتيجة هي نماذج بيانات وطبقة شبكة (تعتمد على URLSession أو Alamofire) وبروتوكولات.

مثال على استخدام CreateAPI

لننظر في توليد عميل لواجهة REST API بسيطة (مثل قائمة المستخدمين).

الخطوة 1. التثبيت

أضف CreateAPI إلى Package.swift أو قم بتثبيته عبر Mint:

// Package.swiftdependencies: [    .package(url: "https://github.com/CreateAPI/CreateAPI", from: "0.2.0")]

الخطوة 2. إعداد مواصفات OpenAPI

مثال api.yaml:

openapi: "3.0.0"info:  title: Users API  version: "1.0"paths:  /users:    get:      summary: Get all users      responses:        '200':          description: Success          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/User'components:  schemas:    User:      type: object      properties:        id:          type: integer        name:          type: string        email:          type: string      required:        - id        - name

الخطوة 3. توليد كود Swift

أنشئ ملف التكوين .createapi.yml:

spec: api.yamloutput: ./Generatedmodule: UsersAPI

قم بتشغيل المولد:

swift run create-api generate

الخطوة 4. استخدام الكود المُولّد

ستحصل على ملفات UsersAPI.swift و Models.swift. مثال على الاستخدام في التطبيق:

import UsersAPI

let client = Client(baseURL: URL(string: "https://api.example.com")!)

Task {    do {        let users: [User] = try await client.users.get()        for user in users {            print("\\(user.name) (\\(user.email))")        }    } catch {        print("خطأ: \\(error.localizedDescription)")    }}