Add OpenAPI documents for the toolchains and Swift evolution APIs

CODEOWNERS

@@ -33,3 +33,5 @@
 /_posts/* @timsneath @tkremenek @shahmishal
 
 /gsoc*/ @ktoso
+
+/openapi/ @czechboy0

_includes/footer.html

@@ -6,6 +6,7 @@
     <p class="privacy">
       <a href="//www.apple.com/privacy/privacy-policy/">Privacy Policy</a>
       <a href="//www.apple.com/legal/privacy/en-ww/cookies/">Cookies</a>
+      <a href="/openapi">API</a>
     </p>
   </div>
   <div class="footer-other">

openapi/TestSwiftOrgClient/.gitignore

@@ -0,0 +1,3 @@
+.build
+.swiftpm
+Package.resolved

openapi/TestSwiftOrgClient/Package.swift

@@ -0,0 +1,38 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let clientNames: [String] = [
+    "swiftorgClient",
+    "downloadswiftorgClient",
+]
+
+let package = Package(
+    name: "TestSwiftOrgClient",
+    platforms: [
+        .macOS(.v13),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "Shared",
+            path: "Shared"
+        )
+    ] + clientNames.map { name in
+        .executableTarget(
+            name: name,
+            dependencies: [
+                "Shared",
+                .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
+            ],
+            path: name,
+            plugins: [
+                .plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator"),
+            ]
+        )
+    }
+)

openapi/TestSwiftOrgClient/README.md

@@ -0,0 +1,54 @@
+# Test Swift.org client
+
+This simple Swift package contains a Swift HTTP Client that can be used to test the Swift.org API.
+
+It is generated from the OpenAPI document of Swift.org and generated using Swift OpenAPI Generator.
+
+## Usage
+
+You can run it either against the Swift.org API or against a locally running API.
+
+By default, the tool runs against the production Swift.org APIs.
+
+Run against production using:
+```
+SWIFTORG_SERVER_NAME=prod swift run swiftorgClient
+DOWNLOADSWIFTORG_SERVER_NAME=prod swift run downloadswiftorgClient
+```
+
+Run against a locally running server using:
+```
+SWIFTORG_SERVER_NAME=local swift run swiftorgClient
+```
+
+The exact server URLs are defined in the OpenAPI document.
+
+If the tool detects a deserialization error, possibly because the OpenAPI document does not correctly parse the returned data, it will exit with a non-zero exit code.
+
+If all test cases run successfully, the tool exits with 0.
+
+Sample output:
+
+```
+% SWIFTORG_SERVER_NAME=prod swift run swiftorgClient
+Testing SwiftOrg API at https://www.swift.org/api/v1...
+✅ listReleases
+✅ listDevToolchains(main, amazonlinux2)
+✅ listDevToolchains(main, centos7)
+✅ listDevToolchains(main, macos)
+✅ listDevToolchains(main, ubi9)
+✅ listDevToolchains(main, ubuntu2004)
+✅ listDevToolchains(main, ubuntu2204)
+✅ listDevToolchains(main, windows10)
+✅ listDevToolchains(6.0, amazonlinux2)
+✅ listDevToolchains(6.0, centos7)
+✅ listDevToolchains(6.0, macos)
+✅ listDevToolchains(6.0, ubi9)
+✅ listDevToolchains(6.0, ubuntu2004)
+✅ listDevToolchains(6.0, ubuntu2204)
+✅ listDevToolchains(6.0, windows10)
+✅ listStaticSDKDevToolchains(main)
+✅ listStaticSDKDevToolchains(6.0)
+% DOWNLOADSWIFTORG_SERVER_NAME=prod swift run downloadswiftorgClient
+✅ listProposals
+```

openapi/TestSwiftOrgClient/Shared/Tester.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+package struct Test: Sendable {
+    package var name: String
+    package var work: @Sendable () async throws -> Void
+
+    package init(name: String, work: @Sendable @escaping () async throws -> Void) {
+        self.name = name
+        self.work = work
+    }
+}
+
+package struct Tester {
+    package static func run(_ tests: [Test]) async throws {
+        var results: [(String, Error?)] = []
+        func runTest(_ test: Test) async {
+            do {
+                try await test.work()
+                results.append((test.name, nil))
+                print("✅ \(test.name)")
+            } catch {
+                results.append((test.name, error))
+                print("❌ \(test.name): \(String(describing: error))")
+            }
+        }
+        for test in tests {
+            await runTest(test)
+        }
+        let failed = results.contains(where: { $0.1 != nil })
+        exit(failed ? 1 : 0)
+    }
+}

openapi/TestSwiftOrgClient/downloadswiftorgClient/Issue847Workaround.swift

@@ -0,0 +1,25 @@
+import OpenAPIRuntime
+import HTTPTypes
+import Foundation
+
+// Workaround for issue: https://github.com/swiftlang/swift-org-website/issues/847
+struct Issue847WorkaroundMiddleware: ClientMiddleware {
+    func intercept(
+        _ request: HTTPRequest,
+        body: HTTPBody?,
+        baseURL: URL,
+        operationID: String,
+        next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?)
+    ) async throws -> (HTTPResponse, HTTPBody?) {
+        var (response, responseBody) = try await next(request, body, baseURL)
+        guard
+            operationID == "listProposals" &&
+            response.status.code == 200 &&
+            response.headerFields[.contentType] == "application/octet-stream"
+        else {
+            return (response, responseBody)
+        }
+        response.headerFields[.contentType] = "application/json"
+        return (response, responseBody)
+    }
+}

openapi/TestSwiftOrgClient/downloadswiftorgClient/Tool.swift

@@ -0,0 +1,43 @@
+import OpenAPIURLSession
+import Foundation
+import Shared
+
+enum DownloadSwiftOrgServerName: String {
+    case prod
+}
+
+@main
+struct Tool {
+    static func main() async throws {
+        let serverURL: URL
+        if
+            let name = ProcessInfo.processInfo.environment["DOWNLOADSWIFTORG_SERVER_NAME"],
+            let serverName = DownloadSwiftOrgServerName(rawValue: name)
+        {
+            switch serverName {
+            case .prod:
+                serverURL = try Servers.Server1.url()
+            }
+        } else {
+            serverURL = try Servers.Server1.url()
+        }
+
+        print("Testing download.swift.org API at \(serverURL.absoluteString)...")
+
+        let client = Client(
+            serverURL: serverURL,
+            transport: URLSessionTransport(),
+            middlewares: [
+                Issue847WorkaroundMiddleware(),
+            ]
+        )
+
+        let tests: [Test] = [
+            .init(
+                name: "listProposals",
+                work: { _ = try await client.listProposals().ok.body.json }
+            ),
+        ]
+        try await Tester.run(tests)
+    }
+}

openapi/TestSwiftOrgClient/downloadswiftorgClient/openapi-generator-config.yaml

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

openapi/TestSwiftOrgClient/downloadswiftorgClient/openapi.yaml

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

openapi/TestSwiftOrgClient/openapi-generator-config.yaml

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

openapi/TestSwiftOrgClient/swiftorgClient/Tool.swift

@@ -0,0 +1,71 @@
+import OpenAPIURLSession
+import Foundation
+import Shared
+
+enum SwiftOrgServerName: String {
+    case prod
+    case local
+}
+
+@main
+struct Tool {
+    static func main() async throws {
+        let serverURL: URL
+        if
+            let name = ProcessInfo.processInfo.environment["SWIFTORG_SERVER_NAME"],
+            let serverName = SwiftOrgServerName(rawValue: name)
+        {
+            switch serverName {
+            case .prod:
+                serverURL = try Servers.Server1.url()
+            case .local:
+                serverURL = try Servers.Server2.url()
+            }
+        } else {
+            serverURL = try Servers.Server1.url()
+        }
+
+        print("Testing swift.org API at \(serverURL.absoluteString)...")
+
+        let client = Client(
+            serverURL: serverURL,
+            transport: URLSessionTransport()
+        )
+
+        var tests: [Test] = [
+            .init(
+                name: "listReleases",
+                work: { _ = try await client.listReleases().ok.body.json }
+            ),
+        ]
+        for branch in Components.Schemas.KnownSourceBranch.allCases {
+            for platform in Components.Schemas.KnownPlatformIdentifier.allCases {
+                tests.append(
+                    .init(
+                        name: "listDevToolchains(\(branch.rawValue), \(platform.rawValue))",
+                        work: {
+                            _ = try await client.listDevToolchains(.init(
+                                path: .init(
+                                    branch: branch,
+                                    platform: platform
+                                )
+                            )).ok.body.json
+                        }
+                    )
+                )
+            }
+        }
+        for branch in Components.Schemas.KnownSourceBranch.allCases {
+            tests.append(
+                .init(
+                    name: "listStaticSDKDevToolchains(\(branch.rawValue))",
+                    work: {
+                        _ = try await client.listStaticSDKDevToolchains(.init(path: .init(branch: branch))).ok.body.json
+                    }
+                )
+            )
+        }
+
+        try await Tester.run(tests)
+    }
+}

openapi/TestSwiftOrgClient/swiftorgClient/openapi-generator-config.yaml

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

openapi/TestSwiftOrgClient/swiftorgClient/openapi.yaml

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