Génération Swagger/OpenAPI pour Swift : outils et exemples de code

Génération Swagger/OpenAPI pour Swift (iOS/macOS)

\n\n

Le développement d'applications mobiles pour iOS et macOS nécessite souvent une intégration avec des API REST. L'écriture manuelle de la couche réseau est un processus laborieux et sujet aux erreurs. Les outils de génération de code basés sur les spécifications OpenAPI (Swagger) permettent de créer automatiquement des modèles Swift typés, des requêtes réseau et même des clients API complets. Cela accélère le développement, réduit le nombre de bogues et facilite la maintenance du code lors des modifications de l'API.

\n\n

Dans cet article, nous examinerons les principaux outils de génération de code Swift à partir de spécifications OpenAPI, montrerons des exemples d'utilisation et donnerons des recommandations pour l'intégration dans des projets iOS/macOS.

\n\n

Outils de génération principaux

\n\n

Aujourd'hui, il existe plusieurs solutions populaires qui prennent en charge Swift en tant que langage cible :

\n\n

\n
• OpenAPI Generator — l'outil open source le plus populaire. Prend en charge de nombreux langages, dont Swift 5 et Combine.
\n
• Swagger Codegen — le prédécesseur d'OpenAPI Generator, toujours pris en charge mais moins flexible.
\n
• Create API — un générateur d'Apple, intégré à Xcode 15+, pour créer des clients à partir de spécifications OpenAPI.
\n

\n\n

Examinons chacun d'eux plus en détail.

\n\n

OpenAPI Generator pour Swift

\n\n

OpenAPI Generator est un outil polyvalent qui peut être utilisé comme CLI, image Docker ou plugin pour Gradle/Maven. Pour Swift, plusieurs générateurs sont disponibles :

\n\n

\n
• swift5 — génération en Swift 5 avec prise en charge de Codable, URLSession et Combine.
\n
• swift5-deprecated — version obsolète pour la rétrocompatibilité.
\n

\n\n

Installation et utilisation

\n\n

Le plus simple est d'utiliser 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

Après exécution, le dossier SwiftClient contiendra un projet Xcode généré avec des modèles, des requêtes API et des tests.

\n\n

Exemple de code généré

\n\n

Supposons que nous ayons une spécification avec un endpoint pour récupérer un utilisateur :

\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 créera le modèle Swift suivant :

\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

Et la méthode API correspondante :

\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

Create API d'Apple (Xcode 15+)

\n\n

Depuis Xcode 15