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

Geração Swagger/OpenAPI para Swift (iOS/macOS): análise completa de ferramentas

O desenvolvimento de aplicativos móveis para iOS/macOS frequentemente requer integração com REST API. Escrever a camada de rede manualmente é trabalhoso e propenso a erros, especialmente com mudanças frequentes na especificação. A solução é gerar código Swift a partir de especificações OpenAPI (anteriormente Swagger). Neste artigo, analisaremos as principais ferramentas, seus recursos e exemplos de uso.

O que é OpenAPI e por que é importante para desenvolvedores Swift?

OpenAPI é um padrão para descrever REST API no formato YAML ou JSON. Ele contém informações sobre todos os endpoints, parâmetros, modelos de dados e códigos de resposta. A geração de código a partir dessa descrição permite:

Criar automaticamente modelos de dados tipados (struct, enum)
Gerar clientes de API seguros com URLs e métodos HTTP corretos
Evitar erros de digitação e inconsistências entre documentação e código
Economizar horas de trabalho repetitivo em atualizações de API

Principais ferramentas para geração Swift

Atualmente, as três abordagens mais populares são:

1. Apollo iOS

Apollo é um poderoso cliente GraphQL, mas seu conjunto de ferramentas também suporta OpenAPI através do plugin apollo-ios-openapi. No entanto, esta solução é mais voltada para GraphQL, então para REST puro é melhor considerar outras opções.

2. CreateAPI

CreateAPI é um gerador moderno, escrito em Swift. Ele suporta OpenAPI 3.0 e 3.1, gera código Swift limpo usando async/await, Combine ou API baseada em closures. É a melhor escolha para novos projetos.

3. Swagger Codegen / OpenAPI Generator

Soluções clássicas da comunidade. Suportam várias linguagens, incluindo Swift 5. A geração ocorre via CLI ou plugins para Gradle/Maven. O resultado são modelos de dados, camada de rede (baseada em URLSession ou Alamofire) e protocolos.

Exemplo de uso do CreateAPI

Vamos considerar a geração de um cliente para uma REST API simples (por exemplo, lista de usuários).

Passo 1. Instalação

Adicione CreateAPI ao Package.swift ou instale via Mint:

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

Passo 2. Preparação da especificação OpenAPI

Exemplo 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

Passo 3. Geração do código Swift

Crie um arquivo de configuração .createapi.yml:

spec: api.yamloutput: ./Generatedmodule: UsersAPI

Execute o gerador:

swift run create-api generate

Passo 4. Uso do código gerado

Como resultado, você obterá os arquivos UsersAPI.swift e Models.swift. Exemplo de uso no aplicativo:

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