Skip to content

Commit ded2701

Browse files
committed
[Update] update README
Also add Chinese instructions
1 parent ebe97dc commit ded2701

2 files changed

Lines changed: 162 additions & 1 deletion

File tree

README.md

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,83 @@
1-
# RaAPIWrapper
1+
# RaAPIWrapper
2+
3+
<p align="center">
4+
<a><img src="https://img.shields.io/badge/language-swift-ffac45.svg"></a>
5+
<a href="https://github.com/rakuyoMo/RaAPIWrapper/releases"><img src="https://img.shields.io/cocoapods/v/RaAPIWrapper.svg"></a>
6+
<a href="https://github.com/rakuyoMo/RaAPIWrapper/blob/main/LICENSE"><img src="https://img.shields.io/cocoapods/l/RaAPIWrapper.svg?style=flat"></a>
7+
</p>
8+
9+
> [中文](https://github.com/rakuyoMo/RaAPIWrapper/blob/main/README_CN.md)
10+
11+
`RaAPIWrapper` uses `@propertyWrapper` to achieve a similar effect to that of defining network requests in the Android `Retrofit` library.
12+
13+
When you have a large number of network request apis in the same file `RaAPIWrapper` can help you define each request in a more aggregated form, so you don't have to jump back and forth within the file.
14+
15+
## Say it before
16+
17+
**Special Note! **: `RaAPIWrapper` is just a syntactic sugar for **defining** web requests. You need to use `Alamofire`, `Moya`, other third-party web framework or call `URLSession` directly to initiate web requests on this basis.
18+
19+
The good thing is that you can easily integrate `RaAPIWrapper` into your existing project with few or no code changes, and `RaAPIWrapper` can coexist very well with the existing web framework in your project.
20+
21+
## Prerequisites
22+
23+
- **iOS 11****macOS 10.13****watchOS 4.0****tvOS 11** or later.
24+
- **Xcode 14** or later required.
25+
- **Swift 5.7** or later required.
26+
27+
## Example
28+
29+
```swift
30+
@GET(/api/v1/no_param)
31+
static var noParamAPI: APIParameterBuilder<()>? = nil
32+
33+
@POST(/api/v1/tuple_param)
34+
static var tupleParamAPI: APIParameterBuilder<(id: Int, name: String?)>? = {
35+
// Eliminate the warning by explicitly converting to `[String: Any?]`.
36+
// Also ensure that `nil` parameters can be filtered.
37+
["id": $0.id, "name": $0.name] as [String: Any?]
38+
}
39+
40+
@POST("/post")
41+
static var postWithModel: APIParameterBuilder<Arg>? = {
42+
// You can have your model follow the `APIParameterConvertible` protocol,
43+
// or use `AnyAPIHashableParameter` to wrap your model in an outer layer.
44+
AnyAPIHashableParameter($0)
45+
}
46+
```
47+
48+
## Install
49+
50+
### CocoaPods
51+
52+
```ruby
53+
pod 'RaAPIWrapper'
54+
```
55+
56+
If your project relies on `Alamofire`, then you may also consider relying on `RaAPIWrapper/AF`. This module provides a wrapper for `ParameterEncoding`.
57+
58+
### Swift Package Manager
59+
60+
- File > Swift Packages > Add Package Dependency
61+
- Add https://github.com/rakuyoMo/RaAPIWrapper.git
62+
- SSelect "Up to Next Major" and fill in the corresponding version number
63+
64+
Or add the following to your `Package.swift` file:
65+
66+
```swift
67+
dependencies: [
68+
.package(
69+
url: "https://github.com/rakuyoMo/RaAPIWrapper.git",
70+
.upToNextMajor(from: "1.0.0")
71+
)
72+
]
73+
```
74+
75+
## Usage
76+
77+
Please refer to the example in `Demo.playground`.
78+
79+
> Since playground depends on `RaAPIWrapper` in the form of Swift Package Manager, please open the project via `Package.swift` first, then select `Demo.playground` from the left navigation bar and run the content.
80+
81+
## License
82+
83+
`RaAPIWrapper` is available under the **MIT** license. For more information, see [LICENSE](LICENSE).

README_CN.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# RaAPIWrapper
2+
3+
<p align="center">
4+
<a><img src="https://img.shields.io/badge/language-swift-ffac45.svg"></a>
5+
<a href="https://github.com/rakuyoMo/RaAPIWrapper/releases"><img src="https://img.shields.io/cocoapods/v/RaAPIWrapper.svg"></a>
6+
<a href="https://github.com/rakuyoMo/RaAPIWrapper/blob/main/LICENSE"><img src="https://img.shields.io/cocoapods/l/RaAPIWrapper.svg?style=flat"></a>
7+
</p>
8+
9+
`RaAPIWrapper` 利用 `@propertyWrapper` 来实现类似于 Android `Retrofit` 库中定义网络请求的效果。
10+
11+
在同一个文件中包含大量的网络请求接口时,`RaAPIWrapper` 可以帮助您以更聚合的形式定义每一个请求,让您不用在文件内来回跳转。
12+
13+
## 说在前面
14+
15+
**特别注意!**`RaAPIWrapper` 仅仅是一个**定义**网络请求的语法糖。您需要在此基础上借助 `Alamofire``Moya` 、其他第三方网络框架或者直接调用 `URLSession` 来发起网络请求。
16+
17+
好的一点是,您只需要修改少量的代码,甚至无需修改代码,就可以很简单地将 `RaAPIWrapper` 集成进您已有的项目,`RaAPIWrapper` 可以很好的和您项目中现有的网络框架共存。
18+
19+
## 基本要求
20+
21+
- 运行 **iOS 11****macOS 10.13****watchOS 4.0****tvOS 11** 及以上版本的设备。
22+
- 使用 **Xcode 14** 及以上版本编译运行。
23+
- **Swift 5.7** 及以上版本。
24+
25+
## 示例
26+
27+
```swift
28+
@GET(/api/v1/no_param)
29+
static var noParamAPI: APIParameterBuilder<()>? = nil
30+
31+
@POST(/api/v1/tuple_param)
32+
static var tupleParamAPI: APIParameterBuilder<(id: Int, name: String?)>? = {
33+
// 通过显式转换为 `[String: Any?]` 来消除警告,同时确保为 `nil` 的参数能够被过滤。
34+
["id": $0.id, "name": $0.name] as [String: Any?]
35+
}
36+
37+
@POST("/post")
38+
static var postWithModel: APIParameterBuilder<Arg>? = {
39+
// 您可以让您的模型遵循 `APIParameterConvertible` 协议,或者使用 `AnyAPIHashableParameter` 在外面包裹一层。
40+
AnyAPIHashableParameter($0)
41+
}
42+
```
43+
44+
## 安装
45+
46+
### CocoaPods
47+
48+
```ruby
49+
pod 'RaAPIWrapper'
50+
```
51+
52+
如果您的项目依赖了 `Alamofire`,那么您还可以考虑依赖 `RaAPIWrapper/AF`。该模块提供了针对 `ParameterEncoding` 的封装。
53+
54+
### Swift Package Manager
55+
56+
- 依次选择 File > Swift Packages > Add Package Dependency
57+
- 输入 https://github.com/rakuyoMo/RaAPIWrapper.git
58+
- 选择 "Up to Next Major" 并填入对应的版本号
59+
60+
或者将下面的内容添加到 `Package.swift` 文件中:
61+
62+
```swift
63+
dependencies: [
64+
.package(
65+
url: "https://github.com/rakuyoMo/RaAPIWrapper.git",
66+
.upToNextMajor(from: "1.0.0")
67+
)
68+
]
69+
```
70+
71+
## 使用
72+
73+
请参考 `Demo.playground` 中的示例。
74+
75+
> 因为 playground 以 Swift Package Manager 的形式依赖 `RaAPIWrapper`,所以请先通过 `Package.swift` 打开项目,再从左侧的导航栏中选择 `Demo.playground`,运行相关内容。
76+
77+
## License
78+
79+
`RaAPIWrapper`**MIT** 许可下可用。 有关更多信息,请参见 [LICENSE](LICENSE) 文件。

0 commit comments

Comments
 (0)