Add deprecated annotations on shorthand functions for deprecated operations (#384)

### Motivation

If an operation is marked as deprecated in the OpenAPI document then the
generated protocol requirement is annotated as deprecated. However, the
shorthand overload for this function, in the protocol extension, was
missing this annotation.

### Modifications

Add deprecated annotation to the generated function in the protocol
extension for deprecated API operations.

### Result

If an operation is marked as deprecated in the OpenAPI document then
both variants of the generated function (the protocol requirement _and_
the protocol extension) are annotated as deprecated.

### Test Plan

Updated the snippet test to include a path with one deprecated operation
and one non-deprecated operation.

### Related Issues

- Fixes #367.

Author: simonjbeaumont

Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/translateAPIProtocol.swift

@@ -78,7 +78,11 @@ extension TypesFileTranslator {
                         )
                     ]
                 )
-                return .commentable(operation.comment, .function(function))
+                if operation.operation.deprecated {
+                    return .commentable(operation.comment, .deprecated(.init(), .function(function)))
+                } else {
+                    return .commentable(operation.comment, .function(function))
+                }
             }
         }
 

Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift

@@ -1868,46 +1868,50 @@ final class SnippetBasedReferenceTests: XCTestCase {
         )
     }
 
-    func testPathsSimplestCase() throws {
-        try self.assertPathsTranslation(
-            """
-            /health:
+    func testPaths() throws {
+        let paths = """
+            /healthOld:
               get:
-                operationId: getHealth
+                operationId: getHealthOld
+                deprecated: true
                 responses:
                   '200':
                     description: A success response with a greeting.
                     content:
                       text/plain:
                         schema:
                           type: string
-            """,
-            """
-            public protocol APIProtocol: Sendable {
-                func getHealth(_ input: Operations.getHealth.Input) async throws -> Operations.getHealth.Output
-            }
-            """
-        )
-    }
-
-    func testPathsSimplestCaseExtension() throws {
-        try self.assertPathsTranslationExtension(
-            """
-            /health:
+            /healthNew:
               get:
-                operationId: getHealth
+                operationId: getHealthNew
                 responses:
                   '200':
                     description: A success response with a greeting.
                     content:
                       text/plain:
                         schema:
                           type: string
-            """,
+            """
+        try self.assertPathsTranslation(
+            paths,
+            """
+            public protocol APIProtocol: Sendable {
+                @available(*, deprecated)
+                func getHealthOld(_ input: Operations.getHealthOld.Input) async throws -> Operations.getHealthOld.Output
+                func getHealthNew(_ input: Operations.getHealthNew.Input) async throws -> Operations.getHealthNew.Output
+            }
+            """
+        )
+        try self.assertPathsTranslationExtension(
+            paths,
             """
             extension APIProtocol {
-                public func getHealth(headers: Operations.getHealth.Input.Headers = .init()) async throws -> Operations.getHealth.Output {
-                    try await getHealth(Operations.getHealth.Input(headers: headers))
+                @available(*, deprecated)
+                public func getHealthOld(headers: Operations.getHealthOld.Input.Headers = .init()) async throws -> Operations.getHealthOld.Output {
+                    try await getHealthOld(Operations.getHealthOld.Input(headers: headers))
+                }
+                public func getHealthNew(headers: Operations.getHealthNew.Input.Headers = .init()) async throws -> Operations.getHealthNew.Output {
+                    try await getHealthNew(Operations.getHealthNew.Input(headers: headers))
                 }
             }
             """