Merge pull request #15 from bow-swift/tomas/consuming-generated-code

Documentation for Consuming generated code

Author: truizlop

Documentation.app/Contents/MacOS/Consuming generated code.playground/Pages/Adding the module to your project.xcplaygroundpage/Contents.swift

@@ -7,4 +7,17 @@
 /*:
  # Adding the module to your project
 
+ After generating a network client using Bow OpenAPI, you will get a folder that contains all files together with the Swift Package manifest that describes the provided artifacts. Adding it to your Xcode Project is as easy as dragging the folder to the left panel in Xcode, and Xcode will automatically trigger the Swift Package Manager to download the dependencies.
+ 
+ ![](/assets/project-tree.png)
+ 
+ Then, you need to add the dependency to the target where you want to use the generated code:
+ 
+ ![](/assets/add-frameworks.png)
+ 
+ Finally, you can import it in your Swift files as:
+ 
+ ```swift
+ import SampleAPI
+ ```
  */

Documentation.app/Contents/MacOS/Consuming generated code.playground/Pages/Customizing the configuration.xcplaygroundpage/Contents.swift

@@ -4,7 +4,92 @@
  title: Customizing the configuration
  */
 // nef:end
+// nef:begin:hidden
+import Bow
+import BowEffects
+import Foundation
+
+public enum DecodingError: Error {}
+
+public protocol ResponseDecoder {
+    func safeDecode<T: Decodable>(_ type: T.Type, from: Data) -> IO<DecodingError, T>
+}
+
+extension JSONDecoder: ResponseDecoder {
+    func safeDecode<T: Decodable>(_ type: T.Type, from data: Data) -> IO<DecodingError, T> {
+        IO.invoke {
+            try! self.decode(type, from: data)
+        }
+    }
+}
+
+enum API {
+    struct Config: Equatable {
+        public let basePath: String
+        public let headers: [String: String]
+        public let session: URLSession
+        public let decoder: ResponseDecoder
+        
+        init (basePath: String, session: URLSession = .shared, decoder: ResponseDecoder = JSONDecoder()) {
+            self.init(basePath: basePath, headers: [:], session: session, decoder: decoder)
+        }
+        
+        private init (basePath: String, headers: [String: String], session: URLSession, decoder: ResponseDecoder) {
+            self.basePath = basePath
+            self.headers = headers
+            self.session = session
+            self.decoder = decoder
+        }
+    }
+}
+
+extension API.Config {
+    func appending(headers: [String: String]) -> API.Config { self }
+    func appending(contentType: API.ContentType) -> API.Config { self }
+    func appendingHeader(value: String, forKey key: String) -> API.Config { self }
+    func appendingHeader(token: String) -> API.Config { self }
+}
+// nef:end
 /*:
  # Customizing the configuration
 
+ Before running any network request, we must provide an `API.Config` object. The minimum setup for this configuration includes a base path for all network requests:
+ */
+let baseConfig = API.Config(basePath: "https://url-to-my-server.com")
+/*:
+ However, this can be customized in different ways to achieve our needs.
+ 
+ ## Adding headers
+ 
+ In some cases we may need to add headers to our requests. They can be added to a base configuration. Note that the original configuration will not be mutated, but a copy will be created with the new appended headers. We can use the following methods:
+ */
+let configWithHeaders1 = baseConfig.appending(headers: ["Accept": "application/json"])
+let configWithHeaders2 = baseConfig.appendingHeader(value: "application/json", forKey: "Accept")
+let configWithHeaders3 = baseConfig.appending(contentType: .json)
+/*:
+ Besides this, all methods in our specification that require a header parameter will add an extension method to `API.Config`, where, if we provide a value, it will add it to the headers with the right key. For instance, if our methods require an authentication token, we may have a method like:
+ */
+let authConfig = baseConfig.appendingHeader(token: "my-secure-token")
+/*:
+ ## Customizing URLSession
+ 
+ By default, the configuration object uses `URLSession.shared`. However, you can create a configuration that uses your custom `URLSession` by passing an instance to the initializer:
+ */
+let customSessionConfig = API.Config(basePath: "https://url-to-my-server.com",
+                                     session: URLSession())
+/*:
+ ## Custom decoding
+ 
+ The generated code uses `JSONDecoder` as a default decoder for the received responses. You can provide your own decoder if your server is sending responses in other formats. In such case, your decoder must implement a protocol named `ResponseDecoder` provided in the generated code.
+ 
+ You may also need to provide a custom `JSONDecoder` depending on the date format that your backend is using. In such case, you can create the decoder:
+ */
+let dateFormatter = DateFormatter()
+dateFormatter.timeStyle = .medium
+let decoder = JSONDecoder()
+decoder.dateDecodingStrategy = .formatted(dateFormatter)
+/*:
+ And then pass it in the creation of the configuration object:
  */
+let customDecodingConfig = API.Config(basePath: "https://url-to-my-server.com",
+                                      decoder: decoder)

Documentation.app/Contents/MacOS/Consuming generated code.playground/Pages/Running a network request.xcplaygroundpage/Contents.swift

@@ -4,7 +4,81 @@
  title: Running a network request
  */
 // nef:end
+// nef:begin:hidden
+import Bow
+import BowEffects
+
+enum API {
+    struct Config {
+        let basePath: String
+    }
+    
+    enum HTTPError: Error {}
+}
+
+struct Customer {
+    let identifier: Int
+    let name: String
+}
+
+typealias Customers = [Customer]
+// nef:end
 /*:
- # Running a network request
+# Running a network request
+
+Bow OpenAPI groups network calls in small, concise protocols that can be accessed through the `API` object. Each generated method returns an `EnvIO<API.Config, API.HTTPError, A>` value, where `A` is the type of the returned value from the network call.
+ 
+ This type represents a suspended computation that still needs a configuration object before running, and when provided so, it describes a computation that either produces an `HTTPError`, or a value of type `A`.
 
+ For instance, considering the generated code provides a `CustomerAPI`:
+*/
+protocol CustomerAPI {
+    func getCustomers() -> EnvIO<API.Config, API.HTTPError, Customers>
+}
+// nef:begin:hidden
+struct CustomerAPIClient: CustomerAPI {
+    func getCustomers() -> EnvIO<API.Config, API.HTTPError, Customers> {
+        EnvIO { _ in
+            IO.invoke {
+                [ Customer(id: 1, name: "Tomás") ]
+            }
+        }
+    }
+}
+
+extension API {
+    var customer: CustomerAPI {
+        CustomerAPIClient()
+    }
+}
+// nef:end
+/*:
+ We can invoke this method as:
+ */
+let customersRequest = API.customer.getCustomers()
+/*:
+ However, this will not run the request. Here, `customersRequest` is just a description of the request that we can manipulate; we can handle potential errors, transform the output type, chain it with other requests and even run them in parallel. We recommend you to read the section for [Effects](https://bow-swift.io/next/docs/effects/overview/) in the documentation for Bow, for further information.
+ 
+ We need to provide an API configuration to this request. To do so, we need a base path that will be used to append the paths to the requests described in the OpenAPI specification.
+ */
+let config = API.Config(basePath: "https://url-to-my-server.com")
+customersRequest.provide(config)
+/*:
+ Finally, we can decide to run the request synchronously or asynchronously, and even change the dispatch queue where it will be executed:
  */
+
+// Synchronous run
+let customers: Customers? =
+    try? customersRequest.provide(config).unsafeRunSync()
+
+let either: Either<API.HTTPError, Customers> =
+    customersRequest.provide(config).unsafeRunSyncEither()
+
+// Asynchronous run
+customersRequest.provide(config).unsafeRunAsync { either in
+    either.fold({ httpError in /* ... */ },
+                { customers in /* ... */ })
+}
+
+// Changing queue
+let customers: Customers? = try? customersRequest.provide(config).unsafeRunSync(on: .background)

Documentation.app/Contents/MacOS/Consuming generated code.playground/Pages/Testing your network calls.xcplaygroundpage/Contents.swift

@@ -4,7 +4,150 @@
  title: Testing your network calls
  */
 // nef:end
+// nef:begin:hidden
+import Bow
+import BowEffects
+
+enum API {
+    struct Config {
+        let basePath: String
+        
+        func stub(json: String, code: Int = 200, endpoint: String = "") -> API.Config {
+            self
+        }
+        
+        func stub(error: Error, code: Int = 400, endpoint: String = "") -> API.Config {
+            self
+        }
+    }
+    
+    enum HTTPError {}
+}
+
+struct Customer: Codable, Equatable {
+    let identifier: Int
+    let name: String
+}
+
+typealias Customers = [Customer]
+
+protocol CustomerAPI {
+    func getCustomers() -> EnvIO<API.Config, API.HTTPError, Customers>
+}
+
+struct CustomerAPIClient: CustomerAPI {
+    func getCustomers() -> EnvIO<API.Config, API.HTTPError, Customers> {
+        EnvIO.pure([])^
+    }
+}
+
+extension API {
+    var customer: CustomerAPI {
+        CustomerAPIClient()
+    }
+}
+
+func assert<T: Codable & Equatable>(_ envIO: EnvIO<API.Config, API.HTTPError, T>,
+                                    withConfig: API.Config,
+                                    succeeds: T,
+                                    _ info: String) {}
+
+// nef:end
 /*:
  # Testing your network calls
 
+ An important part of software development is testing. However, testing networking operations is usually cumbersome. It involves mocking dependencies in order to control the results of the network calls, and often we feel uncertain if we are actually testing our code or the mocks.
+ 
+ Bow OpenAPI generates testing tools as part of its output, so that you can easily test your network calls behave as you expect, without actually going to the network. The tool produces a Swift Package that contains two libraries: one that contains the actual APIs described in the specification, and one with the same name and the suffix `Test` that provides some test utilities. For instance, assuming you invoke the tool as:
+ 
+ ```bash
+ $> bow-openapi --name SampleAPI --schema swagger.yaml --output ./Folder
+ ```
+ 
+ It will create a Swift Package with two modules: `SampleAPI` and `SampleAPITest`. In order to use the testing utilities, you would only need to import them:
+ 
+ ```swift
+ import SampleAPI
+ import SampleAPITest
+ ```
+ 
+ In the following sections we will describe the utilities you have for testing.
+ 
+ ## Stubbing responses
+ 
+ In order to test our code, we need to control the scenarios that we want to test. When it comes to network calls, we usually need to stub the content we want in response of out requests.
+ 
+ All this is done through the `API.Config` object. That means we do not need to modify our production code, but only provide a special configuration for testing. We can actually pass the same configuration that we use for production code, but with a small modification.
+ 
+ Importing the testing module generated by Bow OpenAPI will add some extension methods on `API.Config` to let us stub content. The provided methods are:
+ 
+ - `stub(data: Data)`: stubs a `Data` object in response to any network call.
+ - `stub(error: Error)`: stubs an `Error` in response to any network call.
+ - `stub(json: String)`: stubs a JSON formatted String in response to any network call.
+ - `stub(contentsOfFile: URL)`: stubs the content of a file at a given `URL` in response to any network call.
+ 
+ All these methods allow us to provide content in response to any network call, regardless of the endpoint that is being called. They also have an optional parameter `code`, where we can provide the HTTP response code that we want to receive (e.g. 404, 500, etc.).
+ 
+ For instance, we can stub the response of some JSON content with code 200:
+ */
+let json = """
+{
+    "identifier": 1234,
+    "name": "Tomás"
+}
+"""
+let successConfig = API.Config(basePath: "https://url-to-my-server.com")
+    .stub(json: json, code: 200)
+
+/*:
+ Or we can stub an error with a 404 code:
+ */
+enum CustomerError: Error {
+    case notFound
+}
+
+let failureConfig = API.Config(basePath: "https://url-to-my-server.com")
+    .stub(error: CustomerError.notFound, code: 404)
+/*:
+ Then, depending on the scenario you want to test, you only need use the right configuration:
+ */
+API.customer.getCustomers().provide(successConfig) // Tests the happy path
+API.customer.getCustomers().provide(failureConfig) // Tests the unhappy path
+/*:
+ ## Stacking responses
+ 
+ Stubs can be stacked in the `API.Config`, and they are removed as they are consumed. You can call several times to `stub` and those responses will be returned sequentially.
+ 
+ If your code requires more responses than you have stubbed, you will get an error. Similarly, if you stub more content than you consume in the test, you should call `config.reset()` in order to clear the extra stubbed content.
+ 
+ ## Routing responses
+ 
+ If you are doing integration or end-to-end testing, your tests may perform several network calls in an order that you may not know beforehand. The testing tools provided in the module also let you stub content for a specific endpoint:
+ */
+let routingConfig = API.Config(basePath: "https://url-to-my-server.com")
+    .stub(json: json, code: 200, endpoint: "/customers")
+    .stub(json: "[]", code: 200, endpoint: "/products")
+/*:
+ ## Custom assertions
+ 
+ Finally, the testing module provides custom assertions to test the success and failure scenarios. They are available as extension methods in `XCTest`. Therefore, you could write a test like:
+ */
+func testHappyPath() {
+    let json = """
+    {
+        "identifier": 1234,
+        "name": "Tomás"
+    }
+    """
+    let successConfig = API.Config(basePath: "https://url-to-my-server.com")
+        .stub(json: json, code: 200)
+    let expected = [Customer(identifier: 1234, name: "Tomás")]
+    
+    assert(API.customer.getCustomers(),
+           withConfig: successConfig,
+           succeeds: expected,
+           "Customer API did not return the expected result")
+}
+/*:
+ Notice that Bow OpenAPI does not add conformance to `Equatable` in the generated code. Therefore, is up to the user to define when two value objects are equal by adding the corresponding extension.
  */

Documentation.app/Contents/MacOS/Consuming generated code.playground/contents.xcplayground

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<playground version='6.0' target-platform='ios'>
+<playground version='6.0' target-platform='ios' display-mode='raw'>
     <pages>
         <page name='Adding the module to your project'/>
         <page name='Running a network request'/>

Documentation.app/Contents/MacOS/Generation examples.playground/Pages/Limitations.xcplaygroundpage/Contents.swift

@@ -7,4 +7,19 @@
 /*:
  # Limitations
 
+ Bow OpenAPI is very powerful and generates a ready to use network client in Swift that is as good as the specification you provide. If the specification is poor or flaky, the generated code will have the same problems. Generating code according to this specification is a way of honoring it, but it is important that this contract is also honored by the backend side.
+ 
+ Nevertheless, Bow OpenAPI has some other limitations.
+ 
+ ## Inline data types
+ 
+ In order to have a proper generation, you need to define data models in the `components` section in OpenAPI, or in the `definitions` section in Swagger. Defining your data models inline can result in generated code that is not properly named and therefore difficult to use. Nested data type definition is not supported either; you will need to extract those types to the root of the definition of your models.
+ 
+ ## Error data
+ 
+ If you are specifying data models as part of the error response of an endpoint, Bow OpenAPI will not parse that into a value object. However, you will be able to access such information as it is carried in the `API.HTTPError` value that you will get.
+ 
+ ## Body parameters encoding
+ 
+ Currently, the only supported encoding for body parameters is `application/json`.
  */

Documentation.app/Contents/MacOS/Quick start.playground/Pages/Integration in Xcode.xcplaygroundpage/Contents.swift

@@ -7,4 +7,27 @@
 /*:
  # Integration in Xcode
 
+ Bow OpenAPI can be integrated in Xcode easily to regenerate your network client whenever the specification changes. Assuming you have already installed Bow OpenAPI in your computer, you can follow these steps.
+ 
+ ## Add the specification file
+ 
+ Add the OpenAPI/Swagger specification file to the root of your project, as depicted in the image.
+ 
+ ![](/assets/spec-file.png)
+ 
+ ## Create an Aggregate
+ 
+ Add a new target to your project and select Aggregate, giving it the name you prefer.
+ 
+ ![](/assets/aggregate.png)
+ 
+ ## Run script
+ 
+ Select your recently created Aggregate and go to its Build Phases tab. Add a New Run Script Phase. There, you can invoke the Bow OpenAPI command, passing the values you need for your project.
+ 
+ ![](/assets/build-phase.png)
+ 
+ ## Build
+ 
+ From now on, if you run the scheme corresponding to this Aggregate, it will regenerate the network client based on the specification file. Drag the folder containing the generated code and drop it onto your project, and Swift Package Manager will start fetching your dependencies.
  */