Swagger/OpenAPI Generierung für Swift (iOS/macOS) |…

Swagger/OpenAPI Generierung für Swift (iOS/macOS): vollständiger Überblick über Werkzeuge

Die Entwicklung von mobilen Apps für iOS/macOS erfordert oft die Integration mit REST APIs. Die manuelle Erstellung der Netzwerkschicht ist zeitaufwändig und fehleranfällig, insbesondere bei häufigen Änderungen der Spezifikation. Die Lösung ist die Generierung von Swift-Code aus OpenAPI (ehemals Swagger) Spezifikationen. In diesem Artikel analysieren wir die wichtigsten Werkzeuge, ihre Funktionen und Anwendungsbeispiele.

Was ist OpenAPI und warum braucht ein Swift-Entwickler es?

OpenAPI ist ein Standard zur Beschreibung von REST APIs im YAML- oder JSON-Format. Er enthält Informationen über alle Endpunkte, Parameter, Datenmodelle und Antwortcodes. Die Codegenerierung aus einer solchen Beschreibung ermöglicht:

Automatische Erstellung typisierter Datenmodelle (struct, enum)
Generierung sicherer API-Clients mit korrekten URLs und HTTP-Methoden
Vermeidung von Tippfehlern und Unstimmigkeiten zwischen Dokumentation und Code
Zeitersparnis bei Routineaufgaben bei API-Updates

Wichtigste Werkzeuge für die Swift-Generierung

Aktuell sind drei Ansätze am weitesten verbreitet:

1. Apollo iOS

Apollo ist ein leistungsstarker GraphQL-Client, aber sein Toolkit unterstützt auch OpenAPI über das Plugin apollo-ios-openapi. Diese Lösung ist jedoch eher auf GraphQL ausgerichtet, daher sollten für reines REST andere Optionen in Betracht gezogen werden.

2. CreateAPI

CreateAPI ist ein moderner Generator, der in Swift geschrieben ist. Er unterstützt OpenAPI 3.0 und 3.1, generiert sauberen Swift-Code mit async/await, Combine oder closure-basierten APIs. Dies ist die beste Wahl für neue Projekte.

3. Swagger Codegen / OpenAPI Generator

Klassische Lösungen aus der Community. Sie unterstützen viele Sprachen, einschließlich Swift 5. Die Generierung erfolgt über die CLI oder Plugins für Gradle/Maven. Das Ergebnis sind Datenmodelle, eine Netzwerkschicht (basierend auf URLSession oder Alamofire) und Protokolle.

Beispiel für die Verwendung von CreateAPI

Betrachten wir die Generierung eines Clients für eine einfache REST API (z. B. eine Benutzerliste).

Schritt 1. Installation

Fügen Sie CreateAPI zu Package.swift hinzu oder installieren Sie es über Mint:

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

Schritt 2. Vorbereitung der OpenAPI-Spezifikation

Beispiel 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

Schritt 3. Generierung des Swift-Codes

Erstellen Sie eine Konfigurationsdatei .createapi.yml:

spec: api.yamloutput: ./Generatedmodule: UsersAPI

Starten Sie den Generator:

swift run create-api generate

Schritt 4. Verwendung des generierten Codes

Als Ergebnis erhalten Sie die Dateien UsersAPI.swift und Models.swift. Beispiel für die Verwendung in der App:

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("Fehler: \\(error.localizedDescription)")    }}