diff --git a/templates/apple/Sources/Services/Service.swift.twig b/templates/apple/Sources/Services/Service.swift.twig
index d3226c144..a22770630 100644
--- a/templates/apple/Sources/Services/Service.swift.twig
+++ b/templates/apple/Sources/Services/Service.swift.twig
@@ -14,11 +14,15 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {{~ method.description | swiftComment }}
     ///
     {%~ endif %}
+    {%~ if method.parameters.all | length > 0 %}
+    /// - Parameters:
+    {%~ endif %}
     {%~ for parameter in method.parameters.all %}
-    /// @param {{ parameter | typeName(spec) | raw}} {{ parameter.name | caseCamel }}
+    ///   - {{ parameter.name | caseCamel }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %} (optional){% endif %}
+
     {%~ endfor %}
-    /// @throws Exception
-    /// @return array
+    /// - Throws: Exception if the request fails
+    /// - Returns: {{ method | returnType(spec) | raw }}
     ///
     {%~ if method.type == "webAuth" %}
     @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
@@ -78,11 +82,15 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {{~ method.description | swiftComment }}
     ///
     {%~ endif %}
+    {%~ if method.parameters.all | length > 0 %}
+    /// - Parameters:
+    {%~ endif %}
     {%~ for parameter in method.parameters.all %}
-    /// @param {{ parameter | typeName(spec) | raw}} {{ parameter.name | caseCamel }}
+    ///   - {{ parameter.name | caseCamel }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %} (optional){% endif %}
+
     {%~ endfor %}
-    /// @throws Exception
-    /// @return array
+    /// - Throws: Exception if the request fails
+    /// - Returns: {{ method | returnType(spec) | raw }}
     ///
     {%~ if method.type == "webAuth" %}
     @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
diff --git a/templates/swift/Sources/Services/Service.swift.twig b/templates/swift/Sources/Services/Service.swift.twig
index 6d74ee44b..4c9c37d0e 100644
--- a/templates/swift/Sources/Services/Service.swift.twig
+++ b/templates/swift/Sources/Services/Service.swift.twig
@@ -14,11 +14,15 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {{~ method.description | swiftComment }}
     ///
     {%~ endif %}
+    {%~ if method.parameters.all | length > 0 %}
+    /// - Parameters:
+    {%~ endif %}
     {%~ for parameter in method.parameters.all %}
-    /// @param {{ parameter | typeName(spec) | raw}} {{ parameter.name | caseCamel }}
+    ///   - {{ parameter.name | caseCamel }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %} (optional){% endif %}
+
     {%~ endfor %}
-    /// @throws Exception
-    /// @return array
+    /// - Throws: Exception if the request fails
+    /// - Returns: {{ method | returnType(spec) | raw }}
     ///
     open func {{ method.name | caseCamel | overrideIdentifier }}{% if method.responseModel | hasGenericType(spec) %}<T>{% endif %}(
         {%~ for parameter in method.parameters.all %}
@@ -75,11 +79,15 @@ open class {{ service.name | caseUcfirst | overrideIdentifier }}: Service {
     {{~ method.description | swiftComment }}
     ///
     {%~ endif %}
+    {%~ if method.parameters.all | length > 0 %}
+    /// - Parameters:
+    {%~ endif %}
     {%~ for parameter in method.parameters.all %}
-    /// @param {{ parameter | typeName(spec) | raw}} {{ parameter.name | caseCamel }}
+    ///   - {{ parameter.name | caseCamel }}: {{ parameter | typeName(spec) | raw }}{% if not parameter.required or parameter.nullable %} (optional){% endif %}
+
     {%~ endfor %}
-    /// @throws Exception
-    /// @return array
+    /// - Throws: Exception if the request fails
+    /// - Returns: {{ method | returnType(spec) | raw }}
     ///
     open func {{ method.name | caseCamel }}(
         {%~ for parameter in method.parameters.all %}