Generación de Swagger/OpenAPI para Swift: herramientas y ejemplos de código

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

El desarrollo de aplicaciones móviles para iOS y macOS a menudo requiere la integración con REST API. Escribir manualmente la capa de red es un proceso laborioso y propenso a errores. Las herramientas de generación de código basadas en especificaciones OpenAPI (Swagger) permiten crear automáticamente modelos Swift tipados, solicitudes de red e incluso clientes completos para API. Esto acelera el desarrollo, reduce la cantidad de errores y facilita el mantenimiento del código cuando la API cambia.

En este artículo, revisaremos las principales herramientas para generar código Swift a partir de especificaciones OpenAPI, mostraremos ejemplos de su uso y daremos recomendaciones para la integración en proyectos iOS/macOS.

Principales herramientas de generación

Hoy en día, existen varias soluciones populares que admiten Swift como lenguaje de destino:

• OpenAPI Generator — la herramienta de código abierto más popular. Admite muchos lenguajes, incluyendo Swift 5 y Combine.
• Swagger Codegen — predecesor de OpenAPI Generator, todavía compatible, pero menos flexible.
• Create API — generador de Apple, integrado en Xcode 15+, para crear clientes a partir de especificaciones OpenAPI.

Veamos cada uno con más detalle.

OpenAPI Generator para Swift

OpenAPI Generator es una herramienta universal que se puede usar como CLI, imagen Docker o plugin para Gradle/Maven. Para Swift hay varios generadores disponibles:

• swift5 — generación en Swift 5 con soporte para Codable, URLSession y Combine.
• swift5-deprecated — versión obsoleta para compatibilidad hacia atrás.

Instalación y uso

La forma más sencilla es usar Docker:

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

Después de la ejecución, en la carpeta SwiftClient aparecerá un proyecto Xcode generado con modelos, solicitudes API y pruebas.

Ejemplo de código generado

Supongamos que tenemos una especificación con un endpoint para obtener un usuario:

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

OpenAPI Generator creará el siguiente modelo Swift:

import Foundation

public struct User: Codable {    public let id: Int    public let name: String    public let email: String

    enum CodingKeys: String, CodingKey {        case id        case name        case email    }}

Y el método API correspondiente:

import Foundationimport Combine

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

Create API de Apple (Xcode 15+)

A partir de Xcode 15