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

\n\n

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

\n\n

في هذه المقالة، سنستعرض الأدوات الرئيسية لتوليد كود Swift من مواصفات OpenAPI، ونعرض أمثلة على استخدامها ونقدم توصيات للتكامل في مشاريع iOS/macOS.

\n\n

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

\n\n

يوجد حاليًا العديد من الحلول الشائعة التي تدعم Swift كلغة مستهدفة:

\n\n

OpenAPI Generator — الأداة الأكثر شيوعًا مفتوحة المصدر. تدعم العديد من اللغات بما في ذلك Swift 5 وCombine.
Swagger Codegen — سلف OpenAPI Generator، لا يزال مدعومًا ولكنه أقل مرونة.
Create API — مولد من Apple، مدمج في Xcode 15+، لإنشاء عملاء من مواصفات OpenAPI.

\n\n

دعنا ننظر إلى كل منها بمزيد من التفصيل.

\n\n

OpenAPI Generator لـ Swift

\n\n

OpenAPI Generator هي أداة متعددة الاستخدامات يمكن استخدامها كـ CLI أو صورة Docker أو إضافة لـ Gradle/Maven. تتوفر عدة مولدات لـ Swift:

\n\n

swift5 — التوليد على Swift 5 مع دعم Codable وURLSession وCombine.
swift5-deprecated — إصدار قديم للتوافق مع الإصدارات السابقة.

\n\n

التثبيت والاستخدام

\n\n

أسهل طريقة هي استخدام Docker:

\n\n

docker run --rm -v "${PWD}:/local" \\\n  openapitools/openapi-generator-cli generate \\\n  -i /local/spec.yaml \\\n  -g swift5 \\\n  -o /local/SwiftClient

\n\n

بعد التنفيذ، سيظهر في مجلد SwiftClient مشروع Xcode تم إنشاؤه مع النماذج وطلبات API والاختبارات.

\n\n

مثال على الكود المولد

\n\n

لنفترض أن لدينا مواصفات مع نقطة نهاية للحصول على مستخدم:

\n\n

openapi: 3.0.0\ninfo:\n  title: User API\n  version: 1.0.0\npaths:\n  /users/{id}:\n    get:\n      operationId: getUserById\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema:\n            type: integer\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/User'\ncomponents:\n  schemas:\n    User:\n      type: object\n      properties:\n        id:\n          type: integer\n        name:\n          type: string\n        email:\n          type: string\n      required:\n        - id\n        - name\n        - email

\n\n

سينشئ OpenAPI Generator نموذج Swift التالي:

\n\n

import Foundation\n\npublic struct User: Codable {\n    public let id: Int\n    public let name: String\n    public let email: String\n\n    enum CodingKeys: String, CodingKey {\n        case id\n        case name\n        case email\n    }\n}

\n\n

وطريقة API المقابلة:

\n\n

import Foundation\nimport Combine\n\npublic class UserAPI {\n    public static func getUserById(id: Int) -> AnyPublisher<User, Error> {\n        var request = URLRequest(url: URL(string: "https://api.example.com/users/\\(id)")!)\n        request.httpMethod = "GET"\n        return URLSession.shared.dataTaskPublisher(for: request)\n            .map(\\.data)\n            .decode(type: User.self, decoder: JSONDecoder())\n            .eraseToAnyPublisher()\n    }\n}

\n\n