Add documentation for generated presign API.

awslabs · Oct 31, 2023 · 1b259d5 · 1b259d5
1 parent a83158e
commit 1b259d5
Show file tree

Hide file tree

Showing 5 changed files with 92 additions and 16 deletions.
diff --git a/Sources/Services/AWSPolly/PollyClient.swift b/Sources/Services/AWSPolly/PollyClient.swift
@@ -3,6 +3,9 @@
 @_spi(FileBasedConfig) import AWSClientRuntime
 import ClientRuntime
 import Foundation
+#if canImport(FoundationNetworking)
+import FoundationNetworking
+#endif
 import Logging
 
 public class PollyClient {
@@ -483,6 +486,13 @@ extension PollyClient: PollyClientProtocol {
 }
 
 extension PollyClient {
+    /// Presigns the URL for SynthesizeSpeech operation with the given input object SynthesizeSpeechInput.
+    /// The presigned URL will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for SynthesizeSpeech operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `Foundation.URL`: The presigned URL for SynthesizeSpeech operation.
     public func presignURLForSynthesizeSpeech(input: SynthesizeSpeechInput, expiration: Foundation.TimeInterval) async throws -> Foundation.URL {
         let presignedURL = try await input.presignURL(config: config, expiration: expiration)
         guard let presignedURL else {
@@ -493,6 +503,13 @@ extension PollyClient {
 }
 
 extension PollyClient {
+    /// Presigns the request for SynthesizeSpeech operation with the given input object SynthesizeSpeechInput.
+    /// The presigned request will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for SynthesizeSpeech operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `URLRequest`: The presigned request for SynthesizeSpeech operation.
     public func presignRequestForSynthesizeSpeech(input: SynthesizeSpeechInput, expiration: Foundation.TimeInterval) async throws -> URLRequest {
         let presignedRequest = try await input.presign(config: config, expiration: expiration)
         guard let presignedRequest else {
@@ -501,7 +518,3 @@ extension PollyClient {
         return try await URLRequest(sdkRequest: presignedRequest)
     }
 }
-
-#if canImport(FoundationNetworking)
-import FoundationNetworking
-#endif
diff --git a/Sources/Services/AWSS3/S3Client.swift b/Sources/Services/AWSS3/S3Client.swift
@@ -3,6 +3,9 @@
 @_spi(FileBasedConfig) import AWSClientRuntime
 import ClientRuntime
 import Foundation
+#if canImport(FoundationNetworking)
+import FoundationNetworking
+#endif
 import Logging
 
 public class S3Client {
@@ -5025,6 +5028,13 @@ extension S3Client: S3ClientProtocol {
 }
 
 extension S3Client {
+    /// Presigns the URL for GetObject operation with the given input object GetObjectInput.
+    /// The presigned URL will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for GetObject operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `Foundation.URL`: The presigned URL for GetObject operation.
     public func presignURLForGetObject(input: GetObjectInput, expiration: Foundation.TimeInterval) async throws -> Foundation.URL {
         let presignedURL = try await input.presignURL(config: config, expiration: expiration)
         guard let presignedURL else {
@@ -5035,6 +5045,13 @@ extension S3Client {
 }
 
 extension S3Client {
+    /// Presigns the URL for PutObject operation with the given input object PutObjectInput.
+    /// The presigned URL will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for PutObject operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `Foundation.URL`: The presigned URL for PutObject operation.
     public func presignURLForPutObject(input: PutObjectInput, expiration: Foundation.TimeInterval) async throws -> Foundation.URL {
         let presignedURL = try await input.presignURL(config: config, expiration: expiration)
         guard let presignedURL else {
@@ -5045,6 +5062,13 @@ extension S3Client {
 }
 
 extension S3Client {
+    /// Presigns the request for GetObject operation with the given input object GetObjectInput.
+    /// The presigned request will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for GetObject operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `URLRequest`: The presigned request for GetObject operation.
     public func presignRequestForGetObject(input: GetObjectInput, expiration: Foundation.TimeInterval) async throws -> URLRequest {
         let presignedRequest = try await input.presign(config: config, expiration: expiration)
         guard let presignedRequest else {
@@ -5055,6 +5079,13 @@ extension S3Client {
 }
 
 extension S3Client {
+    /// Presigns the request for PutObject operation with the given input object PutObjectInput.
+    /// The presigned request will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for PutObject operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `URLRequest`: The presigned request for PutObject operation.
     public func presignRequestForPutObject(input: PutObjectInput, expiration: Foundation.TimeInterval) async throws -> URLRequest {
         let presignedRequest = try await input.presign(config: config, expiration: expiration)
         guard let presignedRequest else {
@@ -5065,6 +5096,13 @@ extension S3Client {
 }
 
 extension S3Client {
+    /// Presigns the request for UploadPart operation with the given input object UploadPartInput.
+    /// The presigned request will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for UploadPart operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `URLRequest`: The presigned request for UploadPart operation.
     public func presignRequestForUploadPart(input: UploadPartInput, expiration: Foundation.TimeInterval) async throws -> URLRequest {
         let presignedRequest = try await input.presign(config: config, expiration: expiration)
         guard let presignedRequest else {
@@ -5073,7 +5111,3 @@ extension S3Client {
         return try await URLRequest(sdkRequest: presignedRequest)
     }
 }
-
-#if canImport(FoundationNetworking)
-import FoundationNetworking
-#endif
diff --git a/Sources/Services/AWSSTS/STSClient.swift b/Sources/Services/AWSSTS/STSClient.swift
@@ -3,6 +3,9 @@
 @_spi(FileBasedConfig) import AWSClientRuntime
 import ClientRuntime
 import Foundation
+#if canImport(FoundationNetworking)
+import FoundationNetworking
+#endif
 import Logging
 
 public class STSClient {
@@ -464,6 +467,13 @@ extension STSClient: STSClientProtocol {
 }
 
 extension STSClient {
+    /// Presigns the request for GetCallerIdentity operation with the given input object GetCallerIdentityInput.
+    /// The presigned request will be valid for the given expiration, in seconds.
+    ///
+    /// - Parameter input: The input object for GetCallerIdentity operation used to construct request.
+    /// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.
+    ///
+    /// - Returns: `URLRequest`: The presigned request for GetCallerIdentity operation.
     public func presignRequestForGetCallerIdentity(input: GetCallerIdentityInput, expiration: Foundation.TimeInterval) async throws -> URLRequest {
         let presignedRequest = try await input.presign(config: config, expiration: expiration)
         guard let presignedRequest else {
@@ -472,7 +482,3 @@ extension STSClient {
         return try await URLRequest(sdkRequest: presignedRequest)
     }
 }
-
-#if canImport(FoundationNetworking)
-import FoundationNetworking
-#endif
diff --git a/...ft-codegen/src/main/kotlin/software/amazon/smithy/aws/swift/codegen/PresignerGenerator.kt b/...ft-codegen/src/main/kotlin/software/amazon/smithy/aws/swift/codegen/PresignerGenerator.kt
@@ -61,11 +61,8 @@ class PresignerGenerator : SwiftIntegration {
         if (presignOperations.isNotEmpty()) {
             val symbol = protoCtx.symbolProvider.toSymbol(protoCtx.service)
             protoCtx.delegator.useFileWriter("./${ctx.settings.moduleName}/${symbol.name}.swift") { writer ->
-                // Add special-case import statement for Linux
                 // In Linux, Foundation.URLRequest is moved to FoundationNetworking.
-                writer.write("#if canImport(FoundationNetworking)")
-                writer.write("import FoundationNetworking")
-                writer.write("#endif")
+                writer.addImport(packageName = "FoundationNetworking", importOnlyIfCanImport = true)
             }
         }
     }
@@ -132,6 +129,7 @@ class PresignerGenerator : SwiftIntegration {
             openBlock("extension $clientName {", "}") {
                 val params = listOf("input: $inputType", "expiration: Foundation.TimeInterval")
                 val returnType = "URLRequest"
+                renderDocForPresignAPI(this, op, inputType)
                 openBlock("public func presignRequestFor${op.toUpperCamelCase()}(${params.joinToString()}) async throws -> $returnType {", "}") {
                     write("let presignedRequest = try await input.presign(config: config, expiration: expiration)")
                     openBlock("guard let presignedRequest else {", "}") {
@@ -143,6 +141,18 @@ class PresignerGenerator : SwiftIntegration {
         }
     }
 
+    private fun renderDocForPresignAPI(writer: SwiftWriter, op: OperationShape, inputType: String) {
+        writer.apply {
+            write("/// Presigns the request for ${op.toUpperCamelCase()} operation with the given input object $inputType.")
+            write("/// The presigned request will be valid for the given expiration, in seconds.")
+            write("///")
+            write("/// - Parameter input: The input object for ${op.toUpperCamelCase()} operation used to construct request.")
+            write("/// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.")
+            write("///")
+            write("/// - Returns: `URLRequest`: The presigned request for ${op.toUpperCamelCase()} operation.")
+        }
+    }
+
     private fun resolveOperationMiddleware(protocolGenerator: ProtocolGenerator, op: OperationShape, ctx: CodegenContext): OperationMiddleware {
         val operationMiddlewareCopy = protocolGenerator.operationMiddleware.clone()
         operationMiddlewareCopy.removeMiddleware(op, MiddlewareStep.FINALIZESTEP, "AWSSigningMiddleware")

diff --git a/...re/amazon/smithy/aws/swift/codegen/customization/presignable/PresignableUrlIntegration.kt b/...re/amazon/smithy/aws/swift/codegen/customization/presignable/PresignableUrlIntegration.kt
@@ -160,6 +160,7 @@ class PresignableUrlIntegration(private val presignedOperations: Map<String, Set
             openBlock("extension $clientName {", "}") {
                 val params = listOf("input: $inputType", "expiration: Foundation.TimeInterval")
                 val returnType = "Foundation.URL"
+                renderDocForPresignURLAPI(this, op, inputType)
                 openBlock("public func presignURLFor${op.toUpperCamelCase()}(${params.joinToString()}) async throws -> $returnType {", "}") {
                     write("let presignedURL = try await input.presignURL(config: config, expiration: expiration)")
                     openBlock("guard let presignedURL else {", "}") {
@@ -171,6 +172,18 @@ class PresignableUrlIntegration(private val presignedOperations: Map<String, Set
         }
     }
 
+    private fun renderDocForPresignURLAPI(writer: SwiftWriter, op: OperationShape, inputType: String) {
+        writer.apply {
+            write("/// Presigns the URL for ${op.toUpperCamelCase()} operation with the given input object $inputType.")
+            write("/// The presigned URL will be valid for the given expiration, in seconds.")
+            write("///")
+            write("/// - Parameter input: The input object for ${op.toUpperCamelCase()} operation used to construct request.")
+            write("/// - Parameter expiration: The duration (in seconds) the presigned request will be valid for.")
+            write("///")
+            write("/// - Returns: `Foundation.URL`: The presigned URL for ${op.toUpperCamelCase()} operation.")
+        }
+    }
+
     private fun resolveOperationMiddleware(protocolGenerator: ProtocolGenerator, context: ProtocolGenerator.GenerationContext, op: OperationShape): OperationMiddleware {
         val inputSymbol = MiddlewareShapeUtils.inputSymbol(context.symbolProvider, context.model, op)
         val operationMiddlewareCopy = protocolGenerator.operationMiddleware.clone()