Add Sources/issues/Documentation.docc

.spi.yml

@@ -0,0 +1,5 @@
+version: 1
+builder:
+  configs:
+  - documentation_targets:
+    - GitHubRestAPIIssues

README.md

@@ -62,6 +62,8 @@ import GitHubRestAPIUsers
 ```
 </details>
 
+The [tutorail](https://swiftpackageindex.com/wei18/github-rest-api-swift-openapi/tutorial/use-github-restapi-issues) show you the following example or refer below.
+
 <details>
 <summary>Example of code for enhanced issues comment API</summary>
 

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

@@ -0,0 +1,82 @@
+@Tutorials(time: 10) {
+
+    @XcodeRequirement(title: "Swift 5.9 ", destination: "https://developer.apple.com/download/applications/")
+
+    @Intro(title: "Use a client in a Swift package") {
+        This tutorial guides you use GithubAPI Swift client, from scratch!
+
+        Your Swift package will make use of the Swift OpenAPI Generator plugin to generate the code you'll use to call this API.
+    }
+
+    @Section(title: "Configuring your project to use GitHubRestAPISwiftOpenAPI") {
+        Let's extend this sample package to call `GitHub API`.
+        @Steps {
+            @Step {
+                Update the `Package.swift` by adding the package dependencies.
+                @Code(name: "Package.swift", file: client.Package.1.swift, previousFile: client.Package.0.swift)
+            }
+            @Step {
+                Finally, we need to declare the runtime dependencies for our target.
+                @Code(name: "Package.swift", file: client.Package.2.swift)
+            }
+            @Step {
+                Build the project now to ensure it's configured correctly.
+                @Code(name: "Package.swift", file: client.Package.3.swift)
+            }
+        }
+    }
+
+    @Section(title: "Using the code in your target") {
+
+        Now we're ready to use the Github API Swift code.
+
+        @Steps {
+            @Step {
+                Create a File.swift 
+
+                We'll make changes to this file to make use of the code to call the `GitHubRestAPIIssues` API.
+                @Code(name: "File.swift", file: client.file.0.swift)
+            }
+            @Step {
+                First we'll need to import our 5 runtime dependencies.
+                @Code(name: "File.swift", file: client.file.1.swift)
+            }
+            @Step {
+                Next we'll create an instance of our client.
+
+                Note: `Servers.server1()` is the github service, defined in the OpenAPI document.
+                @Code(name: "File.swift", file: client.file.2.swift)
+            }
+            @Step {
+                Finally, we can use the client to make a request and print the response.
+                @Code(name: "File.swift", file: client.file.3.swift)
+            }
+        }
+    }
+
+    @Section(title: "Pattern matching on the response") {
+        Often we'd want to do a bit more than just print the high-level response
+        value. For example, we might like to branch our code based on the response we
+        received from the server.
+
+        @Steps {
+            @Step {
+                Add a `switch` statement to handle the different possible responses from the server.
+
+                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.
+                @Code(name: "File.swift", file: client.file.4.swift, previousFile: client.file.3.swift)
+            }
+            @Step {
+                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.
+
+                Everything should now compile again.
+                @Code(name: "File.swift", file: client.file.5.swift)
+            }
+            @Step {
+                Finally, let's extract and print the content from the response body.
+
+                The `switch` statement over the body allows you to handle the different content types that are specified for the API operation.
+                @Code(name: "File.swift", file: client.file.6.swift)
+            }
+        }
+    }

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

@@ -0,0 +1,11 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "YourGithubAPIExtension",
+    targets: [
+        .target(
+            name: "YourGithubAPIExtension"
+        )
+    ]
+)

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

@@ -0,0 +1,14 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "YourGithubAPIExtension",
+    dependencies: [
+        .package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "YourGithubAPIExtension"
+        )
+    ]
+)

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

@@ -0,0 +1,17 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "YourGithubAPIExtension",
+    dependencies: [
+        .package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "YourGithubAPIExtension"
+            dependencies: [
+                .product(name: "GitHubRestAPIIssues", package: "GitHubRestAPISwiftOpenAPI"),
+            ],
+        )
+    ]
+)

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

@@ -0,0 +1,17 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "YourGithubAPIExtension",
+    dependencies: [
+        .package(url: "https://github.com/wei18/github-rest-api-swift-openapi.git", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "YourGithubAPIExtension"
+            dependencies: [
+                .product(name: "GitHubRestAPIIssues", package: "GitHubRestAPISwiftOpenAPI"),
+            ],
+        )
+    ]
+)

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

@@ -0,0 +1,8 @@
+//
+//  File.swift
+//  
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation

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

@@ -0,0 +1,12 @@
+//
+//  File.swift
+//  
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes

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

@@ -0,0 +1,21 @@
+//
+//  File.swift
+//  
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes
+
+struct GitHubRestAPIIssuesExtension {
+
+    let client = Client(
+        serverURL: try Servers.server1(),
+        transport: URLSessionTransport()
+    )
+
+}

Sources/issues/Documentation.docc/_Resources/client.file.3.swift

@@ -0,0 +1,23 @@
+//
+//  File.swift
+//  
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes
+
+let client = Client(
+    serverURL: try Servers.server1(),
+    transport: URLSessionTransport()
+)
+
+let response = try await client.issues_sol_list_hyphen_comments(
+    path: .init(owner: "wei18", repo: "github-rest-api-swift-openapi", issue_number: 4)
+)
+
+print(response)

Sources/issues/Documentation.docc/_Resources/client.file.4.swift

@@ -0,0 +1,26 @@
+//
+//  File.swift
+//
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes
+
+let client = Client(
+    serverURL: try Servers.server1(),
+    transport: URLSessionTransport()
+)
+
+let response = try await client.issues_sol_list_hyphen_comments(
+    path: .init(owner: "wei18", repo: "github-rest-api-swift-openapi", issue_number: 4)
+)
+
+switch response {
+case .ok(let okResponse):
+    print(okResponse)
+}

Sources/issues/Documentation.docc/_Resources/client.file.5.swift

@@ -0,0 +1,28 @@
+//
+//  File.swift
+//
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes
+
+let client = Client(
+    serverURL: try Servers.server1(),
+    transport: URLSessionTransport()
+)
+
+let response = try await client.issues_sol_list_hyphen_comments(
+    path: .init(owner: "wei18", repo: "github-rest-api-swift-openapi", issue_number: 4)
+)
+
+switch response {
+case .ok(let okResponse):
+    print(okResponse)
+case .undocumented(statusCode: let statusCode, _):
+    print("🥺 undocumented response: \(statusCode)")
+}

Sources/issues/Documentation.docc/_Resources/client.file.6.swift

@@ -0,0 +1,28 @@
+//
+//  File.swift
+//
+//
+//  Created on 2024/1/8.
+//
+
+import Foundation
+import GitHubRestAPIIssues
+import OpenAPIRuntime
+import OpenAPIURLSession
+import HTTPTypes
+
+let client = Client(
+    serverURL: try Servers.server1(),
+    transport: URLSessionTransport()
+)
+
+let response = try await client.issues_sol_list_hyphen_comments(
+    path: .init(owner: "wei18", repo: "github-rest-api-swift-openapi", issue_number: 4)
+)
+
+switch response {
+case .ok(let okResponse):
+    print(okResponse)
+case .undocumented(statusCode: let statusCode, _):
+    print("🥺 undocumented response: \(statusCode)")
+}