From a97557c42628b2621faf3f8e8c3fa8e1fcaa2b93 Mon Sep 17 00:00:00 2001 From: Wei18 <41205mw@gmail.com> Date: Tue, 9 Jan 2024 00:07:25 +0800 Subject: [PATCH] Add Sources/issues/Documentation.docc --- .spi.yml | 5 ++ README.md | 2 + .../Use GitHub RestAPI Issues.tutorial | 82 +++++++++++++++++++ .../_Resources/client.Package.0.swift | 11 +++ .../_Resources/client.Package.1.swift | 14 ++++ .../_Resources/client.Package.2.swift | 17 ++++ .../_Resources/client.Package.3.swift | 17 ++++ .../_Resources/client.file.0.swift | 8 ++ .../_Resources/client.file.1.swift | 12 +++ .../_Resources/client.file.2.swift | 21 +++++ .../_Resources/client.file.3.swift | 23 ++++++ .../_Resources/client.file.4.swift | 26 ++++++ .../_Resources/client.file.5.swift | 28 +++++++ .../_Resources/client.file.6.swift | 28 +++++++ 14 files changed, 294 insertions(+) create mode 100644 .spi.yml create mode 100644 Sources/issues/Documentation.docc/Use GitHub RestAPI Issues.tutorial create mode 100644 Sources/issues/Documentation.docc/_Resources/client.Package.0.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.Package.1.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.Package.2.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.Package.3.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.0.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.1.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.2.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.3.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.4.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.5.swift create mode 100644 Sources/issues/Documentation.docc/_Resources/client.file.6.swift diff --git a/.spi.yml b/.spi.yml new file mode 100644 index 00000000000..af4bfe4f42b --- /dev/null +++ b/.spi.yml @@ -0,0 +1,5 @@ +version: 1 +builder: + configs: + - documentation_targets: + - GitHubRestAPIIssues diff --git a/README.md b/README.md index 3aaeb85d616..1ec16d7df73 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,8 @@ import GitHubRestAPIUsers ``` +The [tutorail](https://swiftpackageindex.com/wei18/github-rest-api-swift-openapi/tutorial/use-github-restapi-issues) show you the following example or refer below. +
Example of code for enhanced issues comment API diff --git a/Sources/issues/Documentation.docc/Use GitHub RestAPI Issues.tutorial b/Sources/issues/Documentation.docc/Use GitHub RestAPI Issues.tutorial new file mode 100644 index 00000000000..8b546372bdb --- /dev/null +++ b/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) + } + } + } diff --git a/Sources/issues/Documentation.docc/_Resources/client.Package.0.swift b/Sources/issues/Documentation.docc/_Resources/client.Package.0.swift new file mode 100644 index 00000000000..4bdd6bc2294 --- /dev/null +++ b/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" + ) + ] +) diff --git a/Sources/issues/Documentation.docc/_Resources/client.Package.1.swift b/Sources/issues/Documentation.docc/_Resources/client.Package.1.swift new file mode 100644 index 00000000000..070777cb75b --- /dev/null +++ b/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" + ) + ] +) diff --git a/Sources/issues/Documentation.docc/_Resources/client.Package.2.swift b/Sources/issues/Documentation.docc/_Resources/client.Package.2.swift new file mode 100644 index 00000000000..37b78a37414 --- /dev/null +++ b/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"), + ], + ) + ] +) diff --git a/Sources/issues/Documentation.docc/_Resources/client.Package.3.swift b/Sources/issues/Documentation.docc/_Resources/client.Package.3.swift new file mode 100644 index 00000000000..37b78a37414 --- /dev/null +++ b/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"), + ], + ) + ] +) diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.0.swift b/Sources/issues/Documentation.docc/_Resources/client.file.0.swift new file mode 100644 index 00000000000..7597a27345c --- /dev/null +++ b/Sources/issues/Documentation.docc/_Resources/client.file.0.swift @@ -0,0 +1,8 @@ +// +// File.swift +// +// +// Created on 2024/1/8. +// + +import Foundation diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.1.swift b/Sources/issues/Documentation.docc/_Resources/client.file.1.swift new file mode 100644 index 00000000000..d6b8fd593f1 --- /dev/null +++ b/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 diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.2.swift b/Sources/issues/Documentation.docc/_Resources/client.file.2.swift new file mode 100644 index 00000000000..c6996639e2e --- /dev/null +++ b/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() + ) + +} \ No newline at end of file diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.3.swift b/Sources/issues/Documentation.docc/_Resources/client.file.3.swift new file mode 100644 index 00000000000..0a70c7fd5aa --- /dev/null +++ b/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) diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.4.swift b/Sources/issues/Documentation.docc/_Resources/client.file.4.swift new file mode 100644 index 00000000000..8ec2e4ba4b6 --- /dev/null +++ b/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) +} diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.5.swift b/Sources/issues/Documentation.docc/_Resources/client.file.5.swift new file mode 100644 index 00000000000..12e90001829 --- /dev/null +++ b/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)") +} diff --git a/Sources/issues/Documentation.docc/_Resources/client.file.6.swift b/Sources/issues/Documentation.docc/_Resources/client.file.6.swift new file mode 100644 index 00000000000..12e90001829 --- /dev/null +++ b/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)") +}