OctoAPI🐙
Octo 是一个 JSON API 抽象层，建立在 Alamofire 之上，适用于用 Swift 3+ 编写的 iOS 项目。它通过易于使用的 Adapter、Connector 和 Paging 类集，简化了常规且繁琐的 API 连接器配置。
Swift 兼容性
| Swift 版本 | OctoAPI 版本 |
|---|---|
| 4.X | >= 0.5.0 |
| 3.X | < 0.5.0 |
特性✨
- 轻松与任何 REST API 交互
- 包含基于 OAuth 2.0 的
grant-type=password授权的授权类 - 通过切换开关在生产和沙箱环境之间切换
- 易于使用的分页
- 自定义记录器，快速确定任何问题
- 允许自定义以支持其他授权协议（只需创建您自己的自定义类！）
基本用法
如果您配置了所有必要的类，基本用法如下：
- 您使用
OctoRequest类准备您的请求，提供端点、方法等。 - 您以请求为参数调用您的连接器类的
run方法。 - 您使用您的选择解析响应数据
DataParser。
var request = OctoRequest(endpoint: "examples")
ExampleConnector.sharedInstance.run(request: request) { (error, data, paging) in
if error == nil {
if let examples = GlossDataParser.parse(collection: data, withType: ExampleModel.self), let example = examples.first {
//Do anything with the parsed model here
}
}
}示例
GetResponse Blog API 的示例可以在项目的示例目录中找到。
它不使用授权，非常适合测试公开的 API。
安装
- 将
pod 'OctoAPI'添加到您的 Podfile 中。 - 运行
pod install。 - 在您想使用库的地方添加
import OctoAPI。
设置⚒
对于您在项目中使用的每个 API，您需要定义一组类。
OctoConnector子类 —— 作为您将调用的共享实例，用于通过 API 进行调用。它底层实现了Callable协议。如果您需要比 Octo 类提供更多的配置，您需要在您的自定义类中实现Callable协议。- 传递给
Callable类的Adapter协议类，包含您的 API 所有必要的配置 - 如果您的 API 需要授权，则需要
Authorization类（可选） - 如果您想在您的 API 中使用分页功能，则需要
Paging类（可选）
适配器
适配器协议类保存了您在项目中使用的 API 的配置。示例
struct ExampleAPIAdapter : Adapter {
var productionURL: String = "PRODUCTION_URL_HERE"
var productionVersion: String = "PRODUCTION_VERSION_HERE"
var sandboxURL: String = "SANDBOX_URL_HERE"
var sandboxVersion: String = "SANDBOX_VERSION HERE"
var mode : AdapterMode = .sandbox //choose over .sandbox or .production
var errorDomain: String = "com.example.error" //used to map errors
var authorizer: Authorizable? {
get {
let params = ExampleAuthParameters(baseURL: versionedURL)
return GrantTypePasswordAuthorization(parameters: params)
}
}
}解析
这个库还内置了对Gloss的支持——在我看来是最好用的Swift JSON映射库——可以使用GlossDataParser类来使用，如下所示：
//Object parsing
if let example = GlossDataParser.parse(object: data, withType: ExampleModel.self) {
//Do anything with the parsed model here
}
//Collection parsing
if let examples = GlossDataParser.parse(collection: data, withType: ExampleModel.self), let example = examples.first {
//Do anything with the parsed model here
}分页
如果你的API使用分页，创建一个Paging类的子类，重写参数以匹配你的API需求，并在构建请求时调用心构造函数传递limit和offset参数。
从响应中解析的分页数据通过paging参数传递到完成块。
你可以使用默认的方法，其中分页信息被添加到响应的HTTP头中，或者使用你的Paging子类中的自定义实现，通过重写parse(fromResponse:)方法。
授权
这个库内置了对授权的支持。目前，Authorizable协议的唯一实现是GrantTypePasswordAuthorization类，实现了OAuth 2.0密码类型的授权，将访问令牌保存在设备安全的密钥库中。
如果请求过程中令牌过期，实现会调用指定的API获取新的访问令牌，暂停在该连接实例上进行的其他请求。当新的访问令牌被获取时：
你可以使用这个实现，或者如果你的应用程序需要，使用你的带有其他类型授权的自定义类。
要使用授权类，你需要提供一系列参数集，这由AuthorizationParameters协议定义，并将其传递给初始化函数，如下所示：
struct ExampleAuthParameters : AuthorizationParameters {
var endpoint: String = "token"
var serviceName: String = "SERVICE_NAME" //Service name used to store your access token in the Keychain
var clientID: String = ""
var baseURL: String //You are most likely to use a baseURL through initializer to match with your versioned URL of the API
public init(baseURL : String) {
self.baseURL = baseURL
}
}
let params = ExampleAuthParameters(baseURL: versionedURL)
let authorizer = GrantTypePasswordAuthorization(parameters: params)要使用你想要的授权类，将对象作为authorizer参数传递到你的Adapter类。之后，你需要在项目中执行授权，如下所示：
if let authorizer = ExampleAPIConnector.sharedInstance.adapter.authorizer {
let login = ""
let password = ""
authorizer.performAuthorization(login: login, password: password, completion: { (error) in
if error == nil {
//run anything you want after the successful authorization
} else {
//catch any errors
}
})
}待办
- 在调用失败时实现对JSON的错误映射
- 单元测试
贡献
- Fork 它
- 创建您的功能分支（
git checkout -b my-new-feature） - 添加您的更改
- 提交您的更改（
git commit -am '添加一些功能'） - 推向分支（
git push origin my-new-feature） - 创建新的 Pull Request
许可
见 LICENSE