Swagger/OpenAPI генерация для Swift: инструменты и примеры кода

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

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

В этой статье мы рассмотрим основные инструменты для генерации Swift-кода из OpenAPI-спецификаций, покажем примеры их использования и дадим рекомендации по интеграции в проекты iOS/macOS.

Основные инструменты генерации

На сегодняшний день существует несколько популярных решений, которые поддерживают Swift в качестве целевого языка:

• OpenAPI Generator — самый популярный инструмент с открытым исходным кодом. Поддерживает множество языков, включая Swift 5 и Combine.
• Swagger Codegen — предшественник OpenAPI Generator, всё ещё поддерживается, но менее гибок.
• Create API — генератор от Apple, встроенный в Xcode 15+, для создания клиентов из OpenAPI-спецификаций.

Рассмотрим каждый из них подробнее.

OpenAPI Generator для Swift

OpenAPI Generator — универсальный инструмент, который можно использовать как CLI, Docker-образ или плагин для Gradle/Maven. Для Swift доступно несколько генераторов:

• swift5 — генерация на Swift 5 с поддержкой Codable, URLSession и Combine.
• swift5-deprecated — устаревшая версия для обратной совместимости.

Установка и использование

Проще всего использовать Docker:

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

После выполнения в папке SwiftClient появится сгенерированный Xcode-проект с моделями, API-запросами и тестами.

Пример сгенерированного кода

Допустим, у нас есть спецификация с эндпоинтом получения пользователя:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /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 создаст следующую 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
    }
}

И соответствующий API-метод:

import Foundation
import 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 от Apple (Xcode 15+)

Начиная с Xcode 15, Apple добавила встроенную поддержку OpenAPI. Теперь можно импортировать спецификацию прямо в проект и генерировать клиентский код без сторонних инструментов.

Как использовать

1. Откройте Xcode и выберите File → New → File…
2. Выберите шаблон API Client (раздел "Other").
3. Укажите путь к OpenAPI-спецификации (YAML или JSON).
4. Xcode сгенерирует Swift-файлы с моделями и протоколами для запросов.

Генерация использует современные возможности Swift: async/await, Codable и строгую типизацию.

Пример использования с async/await

import Foundation
import MyGeneratedAPI

let client = MyAPIClient(baseURL: URL(string: "https://api.example.com")!)

Task {
    do {
        let user = try await client.getUserById(id: 42)
        print("User: \(user.name