Swagger/OpenAPI генерация для Swift (iOS/macOS)

Swagger/OpenAPI генерация для Swift (iOS/macOS): полный обзор инструментов

Разработка мобильных приложений под iOS/macOS часто требует интеграции с REST API. Вручную писать сетевой слой — трудоёмко и чревато ошибками, особенно при частых изменениях спецификации. Решение — генерация Swift-кода из OpenAPI (ранее Swagger) спецификаций. В этой статье разберём основные инструменты, их возможности и примеры использования.

Что такое OpenAPI и зачем это нужно Swift-разработчику?

OpenAPI — это стандарт описания REST API в формате YAML или JSON. Он содержит информацию о всех эндпоинтах, параметрах, моделях данных и кодах ответов. Генерация кода из такого описания позволяет:

Автоматически создавать типизированные модели данных (struct, enum)
Генерировать безопасные API-клиенты с правильными URL и HTTP-методами
Избежать опечаток и несоответствий между документацией и кодом
Экономить часы рутинной работы при обновлениях API

Основные инструменты для Swift-генерации

На текущий момент наиболее популярны три подхода:

1. Apollo iOS

Apollo — мощный GraphQL-клиент, но его инструментарий также поддерживает OpenAPI через плагин apollo-ios-openapi. Однако это решение больше ориентировано на GraphQL, поэтому для чистого REST лучше рассмотреть другие варианты.

2. CreateAPI

CreateAPI — современный генератор, написанный на Swift. Он поддерживает OpenAPI 3.0 и 3.1, генерирует чистый Swift-код с использованием async/await, Combine или closure-based API. Это лучший выбор для новых проектов.

3. Swagger Codegen / OpenAPI Generator

Классические решения от сообщества. Поддерживают множество языков, включая Swift 5. Генерация происходит через CLI или плагины для Gradle/Maven. Результат — модели данных, слой сети (на базе URLSession или Alamofire) и протоколы.

Пример использования CreateAPI

Рассмотрим генерацию клиента для простого REST API (например, список пользователей).

Шаг 1. Установка

Добавьте CreateAPI в Package.swift или установите через Mint:

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

Шаг 2. Подготовка OpenAPI-спецификации

Пример 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

Шаг 3. Генерация Swift-кода

Создайте конфигурационный файл .createapi.yml:

spec: api.yaml
output: ./Generated
module: UsersAPI

Запустите генератор:

swift run create-api generate

Шаг 4. Использование сгенерированного кода

В результате вы получите файлы UsersAPI.swift и Models.swift. Пример использования в приложении:

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.localizedDescription)")
    }
}

Настройка Swagger Codegen для Swift

Если вы предпочитаете классический подход, используйте OpenAPI Generator CLI:

# Установка через Homebrew
brew install openapi-generator

# Генерация Swift-клиента
openapi-generator generate -i api.yaml -g swift5 -o ./GeneratedSwift

Сгенерированный код будет содержать: