[swift] Swift Moya에서 API 문서 자동화하기

28 Nov 2023

swift

Swift에서 Moya는 네트워크 작업을 쉽게 처리할 수 있는 강력한 라이브러리입니다. Moya는 기존의 URLSession이나 Alamofire보다 추상화된 인터페이스를 제공하여 개발자들이 더욱 효율적으로 네트워크 통신을 구현할 수 있도록 도와줍니다.

하지만 Moya를 사용하여 API 통신을 구현할 때, 문서화는 종종 소홀히 되는 경향이 있습니다. API의 엔드포인트, 파라미터, 응답 형식 등을 정확히 알 수 없기 때문에 개발팀 간의 협업이 어려워질 수 있습니다.

이런 문제를 해결하기 위해 Moya에서 제공하는 기능을 활용하여 API 문서를 자동화할 수 있습니다. 이번 포스트에서는 Swift Moya에서 API 문서 자동화하기에 대해 알아보겠습니다.

1. API Provider 생성

먼저, Moya를 사용하기 위해 MoyaProvider를 생성해야 합니다. API Provider는 Moya의 핵심 역할을 담당하며, 실제 네트워크 요청을 처리하는 객체입니다. 아래와 같이 예시 코드를 작성해봅시다.

import Moya

enum MyAPI {
    case getUser(id: Int)
    case createUser(name: String, email: String)
}

extension MyAPI: TargetType {
    var baseURL: URL {
        return URL(string: "https://api.myapp.com")!
    }
    
    var path: String {
        switch self {
        case .getUser(let id):
            return "/users/\(id)"
        case .createUser:
            return "/users"
        }
    }
    
    var method: Moya.Method {
        switch self {
        case .getUser:
            return .get
        case .createUser:
            return .post
        }
    }
    
    var sampleData: Data {
        return Data()
    }
    
    var task: Task {
        switch self {
        case .getUser, .createUser:
            return .requestPlain
        }
    }
    
    var headers: [String: String]? {
        return nil
    }
}

let provider = MoyaProvider<MyAPI>()

위 코드에서 MyAPI는 사용자 정의한 API 엔드포인트를 정의한 열거형입니다. TargetType 프로토콜을 구현하여 각 API의 baseURL, path, method, sampleData, task, headers를 설정합니다.

2. Swagger 문서 생성

이제 Swagger 문서를 생성할 차례입니다. Swagger는 RESTful API를 문서화하기 위한 대표적인 표준 스펙입니다. Moya에서 제공하는 swaggerJSON 메서드를 사용하여 Swagger JSON 문서를 생성할 수 있습니다. 아래 예시 코드를 참고해보세요.

import Moya_SwiftGen

if let swaggerJSON = try? provider.swaggerJSON() {
    let jsonString = String(data: swaggerJSON, encoding: .utf8)
    // jsonString을 파일에 저장하거나 원하는 대로 활용할 수 있습니다.
}

위 코드에서 provider는 이전 단계에서 생성한 MoyaProvider 객체입니다. swaggerJSON 메서드를 호출하여 Swagger JSON 문서를 얻을 수 있으며, 이를 원하는 방식으로 활용하면 됩니다.

3. 문서 공유하기

마지막으로, 생성한 Swagger 문서를 공유하여 개발팀 혹은 서비스 파트너들과 공유해야 합니다. Swagger에는 다양한 도구와 플랫폼이 지원되므로, 선택한 도구를 사용하여 문서를 공유할 수 있습니다.

일반적으로 Swagger UI나 Redoc 등의 도구를 사용하여 Swagger JSON을 제공하면, 개발자들은 직관적인 UI를 통해 API 문서를 살펴볼 수 있습니다.

결론

Swift Moya는 네트워크 통신을 쉽고 간편하게 처리할 수 있도록 도와주는 강력한 라이브러리입니다. 그리고 Moya가 제공하는 기능을 활용하여 API 문서를 자동화할 수 있다는 것은 매우 유용한 기능입니다.

API 문서의 정확성과 완성도는 개발팀 간의 협업과 개발 생산성에 큰 영향을 미칩니다. 따라서 Moya를 사용하는 프로젝트에서는 API 문서 자동화에 충분한 시간과 노력을 투자하는 것이 좋습니다.