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

Génération Swagger/OpenAPI pour Swift (iOS/macOS) : aperçu complet des outils

Le développement d'applications mobiles pour iOS/macOS nécessite souvent une intégration avec une API REST. Écrire manuellement la couche réseau est laborieux et source d'erreurs, surtout en cas de modifications fréquentes de la spécification. La solution est la génération de code Swift à partir de spécifications OpenAPI (anciennement Swagger). Dans cet article, nous passerons en revue les principaux outils, leurs fonctionnalités et des exemples d'utilisation.

Qu'est-ce qu'OpenAPI et pourquoi un développeur Swift en a-t-il besoin ?

OpenAPI est un standard de description d'API REST au format YAML ou JSON. Il contient des informations sur tous les points de terminaison, paramètres, modèles de données et codes de réponse. La génération de code à partir d'une telle description permet de :

Créer automatiquement des modèles de données typés (struct, enum)
Générer des clients API sécurisés avec des URL et méthodes HTTP correctes
Éviter les fautes de frappe et les incohérences entre la documentation et le code
Gagner des heures de travail répétitif lors des mises à jour de l'API

Principaux outils pour la génération Swift

Actuellement, trois approches sont les plus populaires :

1. Apollo iOS

Apollo est un puissant client GraphQL, mais sa boîte à outils prend également en charge OpenAPI via le plugin apollo-ios-openapi. Cependant, cette solution est davantage orientée vers GraphQL, donc pour du REST pur, il est préférable d'envisager d'autres options.

2. CreateAPI

CreateAPI est un générateur moderne écrit en Swift. Il prend en charge OpenAPI 3.0 et 3.1, génère du code Swift propre en utilisant async/await, Combine ou une API basée sur les closures. C'est le meilleur choix pour les nouveaux projets.

3. Swagger Codegen / OpenAPI Generator

Les solutions classiques de la communauté. Elles prennent en charge de nombreux langages, dont Swift 5. La génération se fait via CLI ou des plugins pour Gradle/Maven. Le résultat comprend des modèles de données, une couche réseau (basée sur URLSession ou Alamofire) et des protocoles.

Exemple d'utilisation de CreateAPI

Considérons la génération d'un client pour une API REST simple (par exemple, une liste d'utilisateurs).

Étape 1. Installation

Ajoutez CreateAPI dans Package.swift ou installez-le via Mint :

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

Étape 2. Préparation de la spécification OpenAPI

Exemple de 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

Étape 3. Génération du code Swift

Créez un fichier de configuration .createapi.yml :

spec: api.yamloutput: ./Generatedmodule: UsersAPI

Lancez le générateur :

swift run create-api generate

Étape 4. Utilisation du code généré

En résultat, vous obtiendrez les fichiers UsersAPI.swift et Models.swift. Exemple d'utilisation dans une application :

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