Generación de Swagger/OpenAPI para Swift (iOS/macOS) |…

Generación de Swagger/OpenAPI para Swift (iOS/macOS): revisión completa de herramientas

El desarrollo de aplicaciones móviles para iOS/macOS a menudo requiere integración con REST API. Escribir manualmente la capa de red es laborioso y propenso a errores, especialmente con cambios frecuentes en la especificación. La solución es la generación de código Swift a partir de especificaciones OpenAPI (anteriormente Swagger). En este artículo, analizaremos las principales herramientas, sus capacidades y ejemplos de uso.

¿Qué es OpenAPI y por qué es necesario para un desarrollador Swift?

OpenAPI es un estándar para describir REST API en formato YAML o JSON. Contiene información sobre todos los endpoints, parámetros, modelos de datos y códigos de respuesta. La generación de código a partir de dicha descripción permite:

Crear automáticamente modelos de datos tipados (struct, enum)
Generar clientes API seguros con URL y métodos HTTP correctos
Evitar errores tipográficos y discrepancias entre la documentación y el código
Ahorrar horas de trabajo rutinario en las actualizaciones de la API

Principales herramientas para la generación en Swift

Actualmente, los tres enfoques más populares son:

1. Apollo iOS

Apollo es un potente cliente GraphQL, pero su conjunto de herramientas también admite OpenAPI a través del plugin apollo-ios-openapi. Sin embargo, esta solución está más orientada a GraphQL, por lo que para REST puro es mejor considerar otras opciones.

2. CreateAPI

CreateAPI es un generador moderno escrito en Swift. Admite OpenAPI 3.0 y 3.1, genera código Swift limpio utilizando async/await, Combine o API basada en closures. Es la mejor opción para proyectos nuevos.

3. Swagger Codegen / OpenAPI Generator

Soluciones clásicas de la comunidad. Admiten múltiples lenguajes, incluido Swift 5. La generación se realiza a través de CLI o plugins para Gradle/Maven. El resultado son modelos de datos, capa de red (basada en URLSession o Alamofire) y protocolos.

Ejemplo de uso de CreateAPI

Consideremos la generación de un cliente para una REST API simple (por ejemplo, una lista de usuarios).

Paso 1. Instalación

Agregue CreateAPI a Package.swift o instálelo a través de Mint:

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

Paso 2. Preparación de la especificación OpenAPI

Ejemplo 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

Paso 3. Generación de código Swift

Cree un archivo de configuración .createapi.yml:

spec: api.yamloutput: ./Generatedmodule: UsersAPI

Ejecute el generador:

swift run create-api generate

Paso 4. Uso del código generado

Como resultado, obtendrá los archivos UsersAPI.swift y Models.swift. Ejemplo de uso en la aplicación:

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