Skip to content

Commit ce18524

Browse files
czechboy0czechboy0
authored
[Docs] Refresh tutorials (#478)
### Motivation Our tutorials were originally written for SOAR 0.1.0, so we need to update them to reflect the best practices as of SOAR 1.0 instead. ### Modifications - Adapted to the new Examples structure (most importantly, point to cloning the Vapor hello world project when writing the client, instead of the GreetingService.) - Added a mention of the shorthand APIs as an alternative to the exhaustive handling. (Still show exhaustive handling first though, as we want to make sure adopters consider that first and even prefer it.) - More minor polish and updates. ### Result Tutorials ready for 1.0 (sans versions, those are changed in #472) ### Test Plan Previewed locally, actually went through all the tutorials and verified they all work.
1 parent 14927ee commit ce18524

31 files changed

+134
-181
lines changed

‎Sources/swift-openapi-generator/Documentation.docc/Articles/Manually-invoking-the-generator-CLI.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,9 @@ As an alternative to invoking the CLI manually, you can also use the package com
4949
Set up the `openapi.yaml` and `openapi-generator-config.yaml` files the same way as you would for the build plugin, and then run:
5050

5151
```console
52-
% swift package plugin generate-code-from-openapi --target GreetingServiceClient
52+
% swift package plugin generate-code-from-openapi --target HelloWorldURLSessionClient
5353
```
5454

55-
This will generate files into the `GreetingServiceClient` target's Sources directory, in a directory called GeneratedSources, which you can then check into your repository.
55+
This will generate files into the `HelloWorldURLSessionClient` target's Sources directory, in a directory called `GeneratedSources`, which you can then check into your repository.
5656

5757
You can also invoke the command from the Xcode UI by control-clicking on a target in the Project Navigator, and selecting the command.

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/Adding-openapi-and-swagger-ui-endpoints.tutorial

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
Additionally, you can host an HTML page that renders the OpenAPI document as interactive documentation that you can use from the browser, for example using [swagger-ui](https://github.com/swagger-api/swagger-ui).
88

99
In this tutorial we'll add both endpoints to our Vapor server.
10-
11-
> Tip: The [OpenAPIEndpointsServer example package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/OpenAPIEndpointsServer) contains the configured Vapor server, in case you want to see the result of this tutorial.
10+
11+
> Tip: The [swagger-ui-endpoint-example package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/swagger-ui-endpoint-example) contains the result of this tutorial, in case you're looking for a working example.
1212
}
1313

1414
@Section(title: "Add an /openapi.yaml endpoint") {
@@ -17,7 +17,7 @@
1717

1818
@Steps {
1919
@Step {
20-
Create a `Public/` directory for serving static content.
20+
In the server package, create a `Public/` directory for serving static content.
2121

2222
@Code(name: "console", file: server-openapi-endpoints.console.0.txt, reset: true)
2323
}
@@ -44,11 +44,11 @@
4444
}
4545
}
4646
@Section(title: "Add a Swagger UI endpoint") {
47-
Now we'll add a static `openapi.html` page that serves Swagger UI and add a redirect to this page from `/` for discoverability.
47+
Now we'll add a static `openapi.html` page that serves Swagger UI and add a redirect to this page from `/openapi` for discoverability.
4848

4949
@Steps {
5050
@Step {
51-
Create the file `Public/openapi.html` with the swagger-ui JavaScript.
51+
Create the file `Public/openapi.html` with the HTML contents as shown on the right.
5252

5353
By placing it in the public directory, it is already reachable at `/openapi.html`.
5454

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/ClientSwiftPM.tutorial

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,13 @@
1414
The API for the service is defined using OpenAPI and you'll create a Swift client for this service, from scratch!
1515

1616
Your Swift package will make use of the Swift OpenAPI Generator plugin to generate the code you'll use to call this API.
17+
18+
> Tip: The [hello-world-urlsession-client-example package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-urlsession-client-example) contains the result of this tutorial, in case you're looking for a working example.
1719
}
1820

1921
@Section(title: "(Optional) Downloading and running the server locally for testing") {
2022

21-
In the next section of the guide we will create a client for this service. In order to execute requests, you can download the example server implementation and run it locally.
23+
In the next section of the guide we will create a client for this service. In order to execute requests, you can download an example server implementation and run it locally.
2224

2325
@Steps {
2426
@Step {
@@ -164,4 +166,21 @@
164166
}
165167
}
166168
}
169+
170+
@Section(title: "Unwrapping the response using the shorthand API") {
171+
If you don't need to handle all the response codes and content types, you can also use the shorthand API on the response and body enums, providing you with throwing getters for unwrapping each value.
172+
173+
These conveniences will throw an error if the received response or content type doesn't match the one you're requesting.
174+
175+
@Steps {
176+
@Step {
177+
Remove the switch statement and replace it with chained access to the `ok` response, to its `body`, to the `json` content type of the body, and finally to the `message` property of the received greeting.
178+
@Code(name: "main.swift", file: client.main.7.swift, previousFile: client.main.6.swift)
179+
}
180+
@Step {
181+
You can now compile and run the executable again and see the response in the console.
182+
@Code(name: "console", file: client.console.4.0.txt)
183+
}
184+
}
185+
}
167186
}

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/ClientXcode.tutorial

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,15 @@
1414
The API for the service is defined using OpenAPI and you'll create a Swift client for this service, from scratch!
1515

1616
Your Xcode project will make use of the Swift OpenAPI Generator plugin to generate the code you'll use to call this API from your existing app.
17+
18+
Note: If you don't already have an existing app project, first create a new SwiftUI-based iOS app Xcode project before continuing.
19+
20+
> Tip: The [HelloWorldiOSClientAppExample package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/HelloWorldiOSClientAppExample) contains the result of this tutorial, in case you're looking for a working example.
1721
}
1822

1923
@Section(title: "(Optional) Downloading and running the server locally for testing") {
2024

21-
In the next section of the guide we will create a client for this service. In order to execute requests, you can download the example server implementation and run it locally.
25+
In the next section of the guide we will create a client for this service. In order to execute requests, you can download an example server implementation and run it locally.
2226

2327
@Steps {
2428
@Step {
@@ -35,7 +39,7 @@
3539
}
3640
}
3741
}
38-
42+
3943
@Section(title: "Configuring your target to use the Swift OpenAPI Generator plugin") {
4044

4145
Let's extend this app to call our `GreetingService` API.
@@ -63,25 +67,23 @@
6367
@Step {
6468
With the configuration files in place, we will add the following three package dependencies: the build plugin, the Runtime library, and a concrete client transport that uses URLSession to send HTTP requests.
6569

66-
Select the project in the Project Navigator again, select the project in the Project Editor, and go to Package Dependencies.
70+
Select the project in the Project Navigator, select the project in the Project Editor, and go to Package Dependencies.
6771
}
6872
@Step {
6973
Under Packages, click the plus button to add a new package dependency.
7074
}
7175
@Step {
7276
Find the `swift-openapi-generator` package in an existing collection, or type in the full URL to the search field at the top: `https://github.com/apple/swift-openapi-generator`.
73-
74-
Change the dependency rule to `Up to Next Minor Version`.
7577
}
7678
@Step {
77-
Since the package provides a build plugin that we will integrate later, do not check any products on the next Choose Package Products screen.
79+
Since the package provides a build plugin that we will integrate later, make sure that on the Choose Package Products screen, the "Add to Target" value is "None" for all products listed.
7880

7981
Click Add Package.
8082
}
8183
@Step {
8284
Repeat the same steps two more times, with the packages `https://github.com/apple/swift-openapi-runtime` and `https://github.com/apple/swift-openapi-urlsession`.
8385

84-
This time, do check the library products to be added to the **GreetingServiceClient target**. Note, this might not be the default target Xcode offers to add the libraries to.
86+
This time, ensure the library products are added to the **GreetingServiceClient target**. Note, this might not be the default target Xcode offers to add the libraries to.
8587
}
8688
@Step {
8789
To finish configuring the build plugin in your target, navigate to the Build Phases tab of the GreetingServiceClient in the Project Editor, and expand the Run Build Tool Plug-ins section.
@@ -110,7 +112,7 @@
110112
@Code(name: "GreetingClient.swift", file: client.xcode.0.swift, reset: true)
111113
}
112114
@Step {
113-
Define a new struct called `GreetingClient` with an initializer and an empty method that will fetch cats using the generated client.
115+
Define a new struct called `GreetingClient` with an initializer and an empty method that will fetch the greeting using the generated client.
114116

115117
@Code(name: "GreetingClient.swift", file: client.xcode.1.swift)
116118
}
@@ -145,6 +147,13 @@
145147

146148
@Code(name: "GreetingClient.swift", file: client.xcode.6.swift)
147149
}
150+
@Step {
151+
Alternatively, if you don't need to handle all the responses and content types exhaustively, you can use the shorthand API to unwrap the received body value.
152+
153+
Note that if the actual received response or content type is different to your requested one, the unwrapping getters will thrown an error.
154+
155+
@Code(name: "GreetingClient.swift", file: client.xcode.6.2.swift)
156+
}
148157
@Step {
149158
Finally, in your app target, integrate the client to fetch the personalized greeting, for example to show it in the UI.
150159

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/ServerSwiftPM.tutorial

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
The API for the service is defined using OpenAPI and you'll create a Swift server for this service, from scratch!
1616

1717
Your Swift package will make use of the Swift OpenAPI Generator plugin to generate the code you'll use to implement this API.
18+
19+
> Tip: The [hello-world-vapor-server-example package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-vapor-server-example) contains the result of this tutorial, in case you're looking for a working example.
1820
}
1921

2022
@Section(title: "Creating a new Swift package") {

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.1.swift

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,7 @@ import PackageDescription
33

44
let package = Package(
55
name: "GreetingServiceClient",
6-
platforms: [
7-
.macOS(.v10_15),
8-
.iOS(.v13),
9-
.tvOS(.v13),
10-
.watchOS(.v6),
11-
],
6+
platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
127
targets: [
138
.executableTarget(
149
name: "GreetingServiceClient"

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.2.swift

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,7 @@ import PackageDescription
33

44
let package = Package(
55
name: "GreetingServiceClient",
6-
platforms: [
7-
.macOS(.v10_15),
8-
.iOS(.v13),
9-
.tvOS(.v13),
10-
.watchOS(.v6),
11-
],
6+
platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
127
dependencies: [
138
.package(url: "https://github.com/apple/swift-openapi-generator", exact: "1.0.0-alpha.1"),
149
.package(url: "https://github.com/apple/swift-openapi-runtime", exact: "1.0.0-alpha.1"),

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.3.swift

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,7 @@ import PackageDescription
33

44
let package = Package(
55
name: "GreetingServiceClient",
6-
platforms: [
7-
.macOS(.v10_15),
8-
.iOS(.v13),
9-
.tvOS(.v13),
10-
.watchOS(.v6),
11-
],
6+
platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
127
dependencies: [
138
.package(url: "https://github.com/apple/swift-openapi-generator", exact: "1.0.0-alpha.1"),
149
.package(url: "https://github.com/apple/swift-openapi-runtime", exact: "1.0.0-alpha.1"),
@@ -18,10 +13,7 @@ let package = Package(
1813
.executableTarget(
1914
name: "GreetingServiceClient",
2015
plugins: [
21-
.plugin(
22-
name: "OpenAPIGenerator",
23-
package: "swift-openapi-generator"
24-
)
16+
.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator"),
2517
]
2618
)
2719
]

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.4.swift

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,7 @@ import PackageDescription
33

44
let package = Package(
55
name: "GreetingServiceClient",
6-
platforms: [
7-
.macOS(.v10_15),
8-
.iOS(.v13),
9-
.tvOS(.v13),
10-
.watchOS(.v6),
11-
],
6+
platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
127
dependencies: [
138
.package(url: "https://github.com/apple/swift-openapi-generator", exact: "1.0.0-alpha.1"),
149
.package(url: "https://github.com/apple/swift-openapi-runtime", exact: "1.0.0-alpha.1"),
@@ -18,20 +13,11 @@ let package = Package(
1813
.executableTarget(
1914
name: "GreetingServiceClient",
2015
dependencies: [
21-
.product(
22-
name: "OpenAPIRuntime",
23-
package: "swift-openapi-runtime"
24-
),
25-
.product(
26-
name: "OpenAPIURLSession",
27-
package: "swift-openapi-urlsession"
28-
),
16+
.product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
17+
.product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
2918
],
3019
plugins: [
31-
.plugin(
32-
name: "OpenAPIGenerator",
33-
package: "swift-openapi-generator"
34-
)
20+
.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator"),
3521
]
3622
)
3723
]

‎Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.5.swift

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,7 @@ import PackageDescription
33

44
let package = Package(
55
name: "GreetingServiceClient",
6-
platforms: [
7-
.macOS(.v10_15),
8-
.iOS(.v13),
9-
.tvOS(.v13),
10-
.watchOS(.v6),
11-
],
6+
platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
127
dependencies: [
138
.package(url: "https://github.com/apple/swift-openapi-generator", exact: "1.0.0-alpha.1"),
149
.package(url: "https://github.com/apple/swift-openapi-runtime", exact: "1.0.0-alpha.1"),
@@ -18,20 +13,11 @@ let package = Package(
1813
.executableTarget(
1914
name: "GreetingServiceClient",
2015
dependencies: [
21-
.product(
22-
name: "OpenAPIRuntime",
23-
package: "swift-openapi-runtime"
24-
),
25-
.product(
26-
name: "OpenAPIURLSession",
27-
package: "swift-openapi-urlsession"
28-
),
16+
.product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
17+
.product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
2918
],
3019
plugins: [
31-
.plugin(
32-
name: "OpenAPIGenerator",
33-
package: "swift-openapi-generator"
34-
)
20+
.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator"),
3521
]
3622
)
3723
]

0 commit comments

Comments
 (0)