Geração Swagger/OpenAPI para Swift (iOS/macOS)

O desenvolvimento de aplicativos móveis para iOS e macOS frequentemente requer integração com REST API. Escrever manualmente a camada de rede é um processo trabalhoso e propenso a erros. As ferramentas de geração de código baseadas em especificações OpenAPI (Swagger) permitem criar automaticamente modelos Swift tipados, requisições de rede e até clientes completos para API. Isso acelera o desenvolvimento, reduz o número de bugs e facilita a manutenção do código quando a API muda.

Neste artigo, vamos explorar as principais ferramentas para gerar código Swift a partir de especificações OpenAPI, mostrar exemplos de uso e dar recomendações para integração em projetos iOS/macOS.

Principais ferramentas de geração

Atualmente, existem várias soluções populares que suportam Swift como linguagem alvo:

OpenAPI Generator — a ferramenta de código aberto mais popular. Suporta várias linguagens, incluindo Swift 5 e Combine.
Swagger Codegen — predecessor do OpenAPI Generator, ainda suportado, mas menos flexível.
Create API — gerador da Apple, integrado ao Xcode 15+, para criar clientes a partir de especificações OpenAPI.

Vamos analisar cada um deles em detalhes.

OpenAPI Generator para Swift

OpenAPI Generator é uma ferramenta versátil que pode ser usada como CLI, imagem Docker ou plugin para Gradle/Maven. Para Swift, existem vários geradores disponíveis:

swift5 — geração em Swift 5 com suporte a Codable, URLSession e Combine.
swift5-deprecated — versão legada para compatibilidade reversa.

Instalação e uso

A maneira mais simples é usar Docker:

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

Após a execução, na pasta SwiftClient será gerado um projeto Xcode com modelos, requisições de API e testes.

Exemplo de código gerado

Suponha que temos uma especificação com um endpoint para obter um usuário:

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

O OpenAPI Generator criará o seguinte 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    }}

E o método de API correspondente:

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()    }}