Skip to content

Commit 7bf90b9

Browse files
wei18wei18
authored
Merge pull request #11 from Wei18/feat/tutorial-for-issues
Add Sources/issues/Documentation.docc
2 parents 25e8cc9 + a97557c commit 7bf90b9

14 files changed

+294
-0
lines changed

‎.spi.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
version: 1
2+
builder:
3+
configs:
4+
- documentation_targets:
5+
- GitHubRestAPIIssues

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ import GitHubRestAPIUsers
6262
```
6363
</details>
6464

65+
The [tutorail](https://swiftpackageindex.com/wei18/github-rest-api-swift-openapi/tutorial/use-github-restapi-issues) show you the following example or refer below.
66+
6567
<details>
6668
<summary>Example of code for enhanced issues comment API</summary>
6769

‎Sources/issues/Documentation.docc/Use GitHub RestAPI Issues.tutorial‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
@Tutorials(time: 10) {
2+
3+
@XcodeRequirement(title: "Swift 5.9 ", destination: "https://developer.apple.com/download/applications/")
4+
5+
@Intro(title: "Use a client in a Swift package") {
6+
This tutorial guides you use GithubAPI Swift client, from scratch!
7+
8+
Your Swift package will make use of the Swift OpenAPI Generator plugin to generate the code you'll use to call this API.
9+
}
10+
11+
@Section(title: "Configuring your project to use GitHubRestAPISwiftOpenAPI") {
12+
Let's extend this sample package to call `GitHub API`.
13+
@Steps {
14+
@Step {
15+
Update the `Package.swift` by adding the package dependencies.
16+
@Code(name: "Package.swift", file: client.Package.1.swift, previousFile: client.Package.0.swift)
17+
}
18+
@Step {
19+
Finally, we need to declare the runtime dependencies for our target.
20+
@Code(name: "Package.swift", file: client.Package.2.swift)
21+
}
22+
@Step {
23+
Build the project now to ensure it's configured correctly.
24+
@Code(name: "Package.swift", file: client.Package.3.swift)
25+
}
26+
}
27+
}
28+
29+
@Section(title: "Using the code in your target") {
30+
31+
Now we're ready to use the Github API Swift code.
32+
33+
@Steps {
34+
@Step {
35+
Create a File.swift
36+
37+
We'll make changes to this file to make use of the code to call the `GitHubRestAPIIssues` API.
38+
@Code(name: "File.swift", file: client.file.0.swift)
39+
}
40+
@Step {
41+
First we'll need to import our 5 runtime dependencies.
42+
@Code(name: "File.swift", file: client.file.1.swift)
43+
}
44+
@Step {
45+
Next we'll create an instance of our client.
46+
47+
Note: `Servers.server1()` is the github service, defined in the OpenAPI document.
48+
@Code(name: "File.swift", file: client.file.2.swift)
49+
}
50+
@Step {
51+
Finally, we can use the client to make a request and print the response.
52+
@Code(name: "File.swift", file: client.file.3.swift)
53+
}
54+
}
55+
}
56+
57+
@Section(title: "Pattern matching on the response") {
58+
Often we'd want to do a bit more than just print the high-level response
59+
value. For example, we might like to branch our code based on the response we
60+
received from the server.
61+
62+
@Steps {
63+
@Step {
64+
Add a `switch` statement to handle the different possible responses from the server.
65+
66+
Something's missing here, and if you recompile your package you'll see that the compiler helpfully tells you that your `switch` statement didn't cover all scenarios.
67+
@Code(name: "File.swift", file: client.file.4.swift, previousFile: client.file.3.swift)
68+
}
69+
@Step {
70+
In the event the server provides a response that doesn't conform to the API specification, you still have an opportunity as a client to handle it gracefully. We'll do so by printing a helpful message, indicating that our client doesn't know what to do with this because it hasn't been updated to handle this kind of response.
71+
72+
Everything should now compile again.
73+
@Code(name: "File.swift", file: client.file.5.swift)
74+
}
75+
@Step {
76+
Finally, let's extract and print the content from the response body.
77+
78+
The `switch` statement over the body allows you to handle the different content types that are specified for the API operation.
79+
@Code(name: "File.swift", file: client.file.6.swift)
80+
}
81+
}
82+
}

‎Sources/issues/Documentation.docc/_Resources/client.Package.0.swift‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// swift-tools-version: 5.9
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "YourGithubAPIExtension",
6+
targets: [
7+
.target(
8+
name: "YourGithubAPIExtension"
9+
)
10+
]
11+
)

‎Sources/issues/Documentation.docc/_Resources/client.Package.1.swift‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// swift-tools-version: 5.9
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "YourGithubAPIExtension",
6+
dependencies: [
7+
.package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
8+
],
9+
targets: [
10+
.target(
11+
name: "YourGithubAPIExtension"
12+
)
13+
]
14+
)

‎Sources/issues/Documentation.docc/_Resources/client.Package.2.swift‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// swift-tools-version: 5.9
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "YourGithubAPIExtension",
6+
dependencies: [
7+
.package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
8+
],
9+
targets: [
10+
.target(
11+
name: "YourGithubAPIExtension"
12+
dependencies: [
13+
.product(name: "GitHubRestAPIIssues", package: "GitHubRestAPISwiftOpenAPI"),
14+
],
15+
)
16+
]
17+
)

‎Sources/issues/Documentation.docc/_Resources/client.Package.3.swift‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// swift-tools-version: 5.9
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "YourGithubAPIExtension",
6+
dependencies: [
7+
.package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
8+
],
9+
targets: [
10+
.target(
11+
name: "YourGithubAPIExtension"
12+
dependencies: [
13+
.product(name: "GitHubRestAPIIssues", package: "GitHubRestAPISwiftOpenAPI"),
14+
],
15+
)
16+
]
17+
)

‎Sources/issues/Documentation.docc/_Resources/client.file.0.swift‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
//
2+
// File.swift
3+
//
4+
//
5+
// Created on 2024/1/8.
6+
//
7+
8+
import Foundation

‎Sources/issues/Documentation.docc/_Resources/client.file.1.swift‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
//
2+
// File.swift
3+
//
4+
//
5+
// Created on 2024/1/8.
6+
//
7+
8+
import Foundation
9+
import GitHubRestAPIIssues
10+
import OpenAPIRuntime
11+
import OpenAPIURLSession
12+
import HTTPTypes

‎Sources/issues/Documentation.docc/_Resources/client.file.2.swift‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
//
2+
// File.swift
3+
//
4+
//
5+
// Created on 2024/1/8.
6+
//
7+
8+
import Foundation
9+
import GitHubRestAPIIssues
10+
import OpenAPIRuntime
11+
import OpenAPIURLSession
12+
import HTTPTypes
13+
14+
struct GitHubRestAPIIssuesExtension {
15+
16+
let client = Client(
17+
serverURL: try Servers.server1(),
18+
transport: URLSessionTransport()
19+
)
20+
21+
}

0 commit comments

Comments
 (0)