Initial commit

Co-authored-by: Honza Dvorsky <[email protected]>
Co-authored-by: Si Beaumont <[email protected]>
Co-authored-by: George Barnett <[email protected]>
Co-authored-by: Gus Cairo <[email protected]>
Co-authored-by: Mario Sangiorgio <[email protected]>

Author: 5 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+### Motivation
+
+_[Explain here the context, and why you're making that change. What is the problem you're trying to solve.]_
+
+### Modifications
+
+_[Describe the modifications you've made.]_
+
+### Result
+
+_[After your change, what will change.]_
+
+### Test Plan
+
+_[Describe the steps you took, or will take, to qualify the change - such as adjusting tests and manual testing.]_

.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+DerivedData/
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.vscode
+/Package.resolved
+.ci/
+.docc-build/

.spi.yml

@@ -0,0 +1,5 @@
+version: 1
+builder:
+  configs:
+  - documentation_targets:
+    - swift-openapi-generator

.swift-format

@@ -0,0 +1,58 @@
+{
+  "fileScopedDeclarationPrivacy" : {
+    "accessLevel" : "private"
+  },
+  "indentation" : {
+    "spaces" : 4
+  },
+  "indentConditionalCompilationBlocks" : false,
+  "indentSwitchCaseLabels" : false,
+  "lineBreakAroundMultilineExpressionChainComponents" : true,
+  "lineBreakBeforeControlFlowKeywords" : false,
+  "lineBreakBeforeEachArgument" : true,
+  "lineBreakBeforeEachGenericRequirement" : true,
+  "lineLength" : 120,
+  "maximumBlankLines" : 1,
+  "prioritizeKeepingFunctionOutputTogether" : false,
+  "respectsExistingLineBreaks" : true,
+  "rules" : {
+    "AllPublicDeclarationsHaveDocumentation" : false,
+    "AlwaysUseLowerCamelCase" : false,
+    "AmbiguousTrailingClosureOverload" : true,
+    "BeginDocumentationCommentWithOneLineSummary" : false,
+    "DoNotUseSemicolons" : true,
+    "DontRepeatTypeInStaticProperties" : false,
+    "FileScopedDeclarationPrivacy" : true,
+    "FullyIndirectEnum" : true,
+    "GroupNumericLiterals" : true,
+    "IdentifiersMustBeASCII" : true,
+    "NeverForceUnwrap" : false,
+    "NeverUseForceTry" : false,
+    "NeverUseImplicitlyUnwrappedOptionals" : false,
+    "NoAccessLevelOnExtensionDeclaration" : false,
+    "NoAssignmentInExpressions" : true,
+    "NoBlockComments" : true,
+    "NoCasesWithOnlyFallthrough" : true,
+    "NoEmptyTrailingClosureParentheses" : true,
+    "NoLabelsInCasePatterns" : false,
+    "NoLeadingUnderscores" : false,
+    "NoParensAroundConditions" : true,
+    "NoVoidReturnOnFunctionSignature" : true,
+    "OneCasePerLine" : true,
+    "OneVariableDeclarationPerLine" : true,
+    "OnlyOneTrailingClosureArgument" : true,
+    "OrderedImports" : false,
+    "ReturnVoidInsteadOfEmptyTuple" : true,
+    "UseEarlyExits" : true,
+    "UseLetInEveryBoundCaseVariable" : false,
+    "UseShorthandTypeNames" : true,
+    "UseSingleLinePropertyGetter" : false,
+    "UseSynthesizedInitializer" : true,
+    "UseTripleSlashForDocumentationComments" : true,
+    "UseWhereClausesInForLoops" : false,
+    "ValidateDocumentationComments" : false
+  },
+  "spacesAroundRangeFormationOperators" : false,
+  "tabWidth" : 8,
+  "version" : 1
+}

CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+The code of conduct for this project can be found at https://swift.org/code-of-conduct.
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+## Legal
+
+By submitting a pull request, you represent that you have the right to license
+your contribution to Apple and the community, and agree by submitting the patch
+that your contributions are licensed under the Apache 2.0 license (see
+`LICENSE.txt`).
+
+## How to submit a bug report
+
+Please ensure to specify the following:
+
+* Commit hash
+* Contextual information (e.g. what you were trying to achieve with swift-openapi-generator)
+* Simplest possible steps to reproduce
+  * More complex the steps are, lower the priority will be.
+  * A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description.
+* Anything that might be relevant in your opinion, such as:
+  * Swift version or the output of `swift --version`
+  * OS version and the output of `uname -a`
+  * Network configuration
+
+### Example
+
+```
+Commit hash: b17a8a9f0f814c01a56977680cb68d8a779c951f
+
+Context:
+While testing my application that uses with swift-openapi-generator, I noticed that ...
+
+Steps to reproduce:
+1. ...
+2. ...
+3. ...
+4. ...
+
+$ swift --version
+Swift version 4.0.2 (swift-4.0.2-RELEASE)
+Target: x86_64-unknown-linux-gnu
+
+Operating system: Ubuntu Linux 16.04 64-bit
+
+$ uname -a
+Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux
+
+My system has IPv6 disabled.
+```
+
+## Writing a Patch
+
+A good patch is:
+
+1. Concise, and contains as few changes as needed to achieve the end result.
+2. Tested, ensuring that any tests provided failed before the patch and pass after it.
+3. Documented, adding API documentation as needed to cover new functions and properties.
+4. Accompanied by a great commit message, using our commit message template.
+
+### Run `./scripts/soundness.sh`
+
+The scripts directory contains a [soundness.sh script](https://github.com/apple/swift-openapi-generator/blob/main/scripts/soundness.sh) 
+that enforces additional checks, like license headers and formatting style.
+
+Please make sure to `./scripts/soundness.sh` before pushing a change upstream, otherwise it is likely the PR validation will fail
+on minor changes such as a missing `self.` or similar formatting issues.
+
+For frequent contributors, we recommend adding the script as a [git pre-push hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), which you can do via executing the following command in the project root directory: 
+
+```bash
+cat << EOF > .git/hooks/pre-push
+
+if [[ -f "scripts/soundness.sh" ]]; then
+  scripts/soundness.sh
+fi
+EOF
+```
+
+Which makes the script execute, and only allow the `git push` to complete if the check has passed.
+
+In the case of formatting issues, you can then `git add` the formatting changes, and attempt the push again. 
+
+## How to contribute your work
+
+Please open a pull request at https://github.com/apple/swift-openapi-generator. Make sure the CI passes, and then wait for code review.

CONTRIBUTORS.txt

@@ -0,0 +1,22 @@
+For the purpose of tracking copyright, this is the list of individuals and
+organizations who have contributed source code to SwiftOpenAPIGenerator.
+
+For employees of an organization/company where the copyright of work done
+by employees of that company is held by the company itself, only the company
+needs to be listed here.
+
+## COPYRIGHT HOLDERS
+
+- Apple Inc. (all contributors with '@apple.com')
+
+### Contributors
+
+- George Barnett <[email protected]>
+- Gus Cairo <[email protected]>
+- Honza Dvorsky <[email protected]>
+- Mario Sangiorgio <[email protected]>
+- Si Beaumont <[email protected]>
+
+**Updating this list**
+
+Please do not edit this file manually. It is generated using `./scripts/generate-contributors-list.sh`. If a name is misspelled or appearing multiple times: add an entry in `./.mailmap`

Examples/GreetingService/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+DerivedData/
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.vscode
+/Package.resolved
+.ci/
+.docc-build/

Examples/GreetingService/Package.swift

@@ -0,0 +1,61 @@
+// swift-tools-version:5.8
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import PackageDescription
+
+let package = Package(
+    name: "GreetingService",
+    platforms: [
+        .macOS(.v13)
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", .upToNextMinor(from: "0.1.0")),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", .upToNextMinor(from: "0.1.0")),
+        .package(url: "https://github.com/apple/swift-openapi-urlsession", .upToNextMinor(from: "0.1.0")),
+        .package(url: "https://github.com/swift-server/swift-openapi-vapor", .upToNextMinor(from: "0.1.0")),
+        .package(url: "https://github.com/vapor/vapor", from: "4.76.0"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "GreetingService",
+            dependencies: [
+                .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIVapor", package: "swift-openapi-vapor"),
+                .product(name: "Vapor", package: "vapor"),
+            ],
+            plugins: [
+                .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")
+            ]
+        ),
+
+        .executableTarget(
+            name: "GreetingServiceClient",
+            dependencies: [
+                .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
+            ],
+            plugins: [
+                .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")
+            ]
+        ),
+
+        .testTarget(
+            name: "GreetingServiceMockTests",
+            dependencies: [
+                "GreetingService",
+                .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+            ]
+        ),
+    ]
+)

Examples/GreetingService/Sources/GreetingService/GreetingService.swift

@@ -0,0 +1,51 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import OpenAPIRuntime
+import OpenAPIVapor
+import Vapor
+
+// User provides a type that adopts `APIProtocol` (a generated protocol).
+struct Handler: APIProtocol {
+
+    // This function is a protocol requirement, derived from the operation in the OpenAPI document.
+    func getGreeting(
+        _ input: Operations.getGreeting.Input
+    ) async throws -> Operations.getGreeting.Output {
+        // Extract the query parameter from the input, using generated type-safe property.
+        let name = input.query.name ?? "Stranger"
+
+        // Return a OK response (HTTP status 200) with a JSON body, using a type-safe output.
+        return .ok(.init(body: .json(.init(message: "Hello, \(name)!"))))
+    }
+}
+
+@main
+struct Main {
+    public static func main() throws {
+        // Create a Vapor application.
+        let app = Vapor.Application()
+
+        // Create a ServerTransport using the Vapor application.
+        let transport = VaporTransport(routesBuilder: app)
+
+        // Create an instance of the handler type that conforms the generated APIProtocol.
+        let handler = Handler()
+
+        // Call the generated protocol function on the handler to configure the Vapor application.
+        try handler.registerHandlers(on: transport, serverURL: Servers.server1())
+
+        // Start the Vapor application, in the same way as if it was manually configured.
+        try app.run()
+    }
+}

Examples/GreetingService/Sources/GreetingService/openapi-generator-config.yaml

@@ -0,0 +1,3 @@
+generate:
+- types
+- server

Examples/GreetingService/Sources/GreetingService/openapi.yaml

@@ -0,0 +1 @@
+../../openapi.yaml

Examples/GreetingService/Sources/GreetingServiceClient/GreetingServiceClient.swift

@@ -0,0 +1,46 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import OpenAPIRuntime
+import OpenAPIURLSession
+
+@main
+struct GreetingServiceClient {
+
+    static func main() async throws {
+        // Create an instance of the generated client type.
+        let client: APIProtocol = Client(
+            // Server.server1() is generated, derived from the server URL in the OpenAPI document.
+            serverURL: try Servers.server1(),
+            // URLSessionTransport conforms to ClientTransport and is provided by a separate package.
+            transport: URLSessionTransport()
+        )
+
+        // Make an API call using generated type-safe Operations.getGreeting.Input.
+        let response = try await client.getGreeting(.init(query: .init(name: "Jane")))
+
+        // Operations.getGreeting.Output is an enum that models all the documented responses.
+        switch response {
+        case .ok(let response):
+            // The response body is also an enum value that models all the documented content-types.
+            switch response.body {
+            case .json(let greeting):
+                // The associated enum value is a generated value type derived from the OpenAPI document.
+                print(greeting.message)
+            }
+        // In the event the server responds with something that isn't in its documented API.
+        case .undocumented(statusCode: let statusCode, let undocumentedPayload):
+            print("Undocumented response \(statusCode) from server: \(undocumentedPayload).")
+        }
+    }
+}

Examples/GreetingService/Sources/GreetingServiceClient/openapi-generator-config.yaml

@@ -0,0 +1,3 @@
+generate:
+- types
+- client

Examples/GreetingService/Sources/GreetingServiceClient/openapi.yaml

@@ -0,0 +1 @@
+../../openapi.yaml