[iOS/Swift] Swift OpenApi Generator

참고할 WWDC

Meet Swift OpenAPI Generator - WWDC23 - Videos - Apple Developer

 

일단 이 WWDC 내용을 요약하자면,,

 

Swift OpenAPI Generator는 서버 API 작업을 간소화하는 새로운 Swift 패키지 플러그인이다.

 

Swift OpenApi Generator 주요특징

1. 필요한 패키지 의존성 추가:
   • swift-openapi-generator (플러그인 제공)
   • swift-openapi-runtime (공통 타입과 추상화 제공)
   • 선택한 HTTP 클라이언트용 통합 패키지 (예: URLSession)
2. 타겟 설정에서 OpenAPI Generator 플러그인 구성:
   • Build Phases > Run Build Tool Plug-ins에서 플러그인 추가
   • 소스 디렉토리에 OpenAPI 문서와 플러그인 구성 파일 추가
3. 플러그인 구성 파일에서 생성할 코드 지정:
   • "types": OpenAPI 문서에서 파생된 재사용 가능한 타입
   • "client": HTTP 클라이언트로 API 호출을 만드는 데 사용할 수 있는 코드
4. 생성된 Client 타입을 사용하여 API 호출:

let client = Client(...)
let response = try await client.getEmoji(...)
// 응답 처리

 

서버 측 사용법

1. Swift 패키지에 필요한 의존성 추가:
   • swift-openapi-generator
   • swift-openapi-runtime
   • 웹 프레임워크 통합 패키지 (예: swift-openapi-vapor)
2. 플러그인 구성 파일에서 생성할 코드 지정:
   • "types"
   • "server": 서버 스텁 코드
3. 생성된 APIProtocol을 준수하는 타입 정의:
   • API 작업에 대한 비즈니스 로직만 구현
   • 생성된 registerHandlers 함수를 사용하여 HTTP 서버와 핸들러 연결

 

---

 

왜 쓰는거지?

클라이언트 개발은 본질적으로 백엔드 API에 의존적입니다. (대부분 백엔드 변경사항이 프론트엔드에 직접적인 영향을 미침). 문제는 클라이언트 개발자가 별도의 서비스인 백엔드의 변화를 사전에 코드 레벨에서 예측하거나 대비하기 어려운데 Swift OpenAPI Generator는 이러한 불확실성을 크게 줄일수 있습니다.

백엔드 API가 변경될 경우, 해당 변경사항은 OpenAPI 명세에 반영되고, 이를 통해 생성되는 코드에도 즉시 반영됩니다. 이런 방식으로 개발자는 컴파일 타임에 API 변경점을 명확히 파악하고 대응할 수 있습니다. 수동으로 API 문서를 읽고 코드를 변경하는 대신, 시스템이 자동으로 변경점을 알려주므로 휴먼 에러를 크게 줄일 수 있습니다.

 

 

 

하는방법

openapi.yaml 파일을 준비합니다.

swagger를 사용하신다면 여기에서 raw 파일을 확인할 수 있습니다.

 

스웨거 맨~위에 있는곳

 

(그리고 이 사이트를 통해 올바른 OAS문서 형태인지 검증할 수 있습니다!)

 

 

프로젝트에 Swift OpenAPI Generator 설정하기

먼저 Xcode 프로젝트에 필요한 패키지 의존성을 추가해야 합니다.

이 세가지 넣어주기!

• https://github.com/apple/swift-openapi-generator
• https://github.com/apple/swift-openapi-runtime
• https://github.com/apple/swift-openapi-urlsession

GitHub - apple/swift-openapi-urlsession: URLSession transport for Swift OpenAPI Generator.

 

 

 

⚠️ 단,swift-openapi-generator 의 경우에는 빌드 플러그인으로 사용되며, 앱 실행 시에는 필요하지 않고 빌드 시점에만 사용됩니다. 따라서 직접 타겟에 추가하지 않고 빌드 플러그인으로 구성해야 합니다.⚠️

즉, 타겟을 직접 설정하지 말고 해당 라이브러리만 논타겟으로 넣어주어야 동작합니다‼️

 

 

• swift-openapi-runtime: 생성된 코드가 실행 시 사용하는 런타임 라이브러리입니다. 요청/응답 처리, 직렬화/역직렬화, 유효성 검사 등 OpenAPI와 관련된 공통 기능을 제공
• swift-openapi-urlsession: URLSession을 기반으로 한 네트워크 전송 구현체. 생성된 API 클라이언트가 실제로 네트워크 요청을 보내고 응답을 받을수 있다.

 

이 두개는 정상적으로 타겟에 넣어도 됩니다.

 

2. 플러그인 설정 파일 만들기

프로젝트의 타겟 소스 디렉토리에 openapi-generator-config.yaml 파일을 생성하고 다음 내용을 추가합니다

generate:
  - types
  - client

 

Type

types 옵션은 OpenAPI 문서에 정의된 스키마를 기반으로 Swift 타입을 생성합니다

• API 요청 및 응답 데이터 모델에 해당하는 Swift 구조체
• API 엔드포인트 매개변수를 위한 타입
• API 응답을 나타내는 열거형
• 공통 구성요소 및 재사용 가능한 스키마

예를 들어, API가 User 객체를 반환한다면

public struct User: Codable, Equatable, Hashable {
    public var id: Int
    public var name: String
    public var email: String?

    public init(id: Int, name: String, email: String? = nil) {
        self.id = id
        self.name = name
        self.email = email
    }
}

이러한 타입들은 클라이언트 코드나 서버 코드에서 API와 상호작용할 때 사용됩니다.

client

API와 통신하기 위한 클라이언트 코드를 생성합니다.

• API 작업을 호출하기 위한 Client 클래스
• 각 API 엔드포인트에 대한 메서드
• 요청 구성 및 응답 처리 로직
• 에러 처리 메커니즘
• 프로토콜 정의(테스트와 목업용)

예를 들어, 사용자 정보를 가져오는 API 엔드포인트가 있다면,

extension Client {
    public func getUser(id: Int) async throws -> Operations.getUser.Output {
        try await self.send(.getUser(id: id))
    }
}

즉, client 없이 인터페이스와 DTO만 사용하고 싶다면 generate부분에 types만 남기면됩니다.

 

 

 

4. 빌드 플러그인 설정

1. Xcode Target 설정으로 이동 → Build Phases →Run Build Tool Plug-ins
2. "+"를 클릭하고 "OpenAPIGenerator" 플러그인을 선택합니다.

 

5. 프로젝트 컴파일

이제 프로젝트를 컴파일하면 OpenAPI Generator가 스웨거 파일에서 코드를 생성합니다. 처음 실행할 때는 플러그인을 신뢰하라는 메시지가 나오는데 trust 한번 눌러주면 됩니다.

생성된 코드는 어디서 보죠?

derived data 내부에 생성됩니다!

 

 

이제 이렇게 생성을 했다면, 기존에 있던 코드들을 전부 대체할수 있게 됩니다.

Moya를 사용했다면

• TargetType
• Provider 설정
• Service 구현
• 응답 모델
• 에러 처리

Alamofire 사용했다면

• Router/EndPoint 정의
• Session 관리
• 요청 함수: AF.request().responseDecodable 형태의 요청 코드
• 응답 처리: dataResponse 콜백 또는 비동기 함수에서 응답 처리
• 에러 핸들링

등을 대체할 수 있게 됩니다!

 

 

Ref

https://dokit.tistory.com/69

[iOS] Swift로 Open API Generator 사용하기

 

https://www.swift.org/blog/introducing-swift-openapi-generator/

Introducing Swift OpenAPI Generator

 

https://github.com/apple/swift-openapi-generator

GitHub - apple/swift-openapi-generator: Generate Swift client and server code from an OpenAPI document.