Fix: Removes example property in path parameter objects (#92)

* Remove example property in Parameters

This helps in avoiding duplication with examples property. They are mutually exclusive. DocumentationURL prop. which used to be set in example property is now set within descriptions property.

* Update src/Microsoft.OpenApi.OData.Reader/Operation/OperationHandler.cs

Co-authored-by: Charles Wahome <[email protected]>

* Remove duplicate variable declaration

* Minor refactoring

To help trigger build

Co-authored-by: Irvine Sunday <[email protected]>
Co-authored-by: Charles Wahome <[email protected]>
Co-authored-by: Sam Xu <[email protected]>

Author: 3 people

src/Microsoft.OpenApi.OData.Reader/Operation/OperationHandler.cs

@@ -1,4 +1,4 @@
-// ------------------------------------------------------------
+// ------------------------------------------------------------
 //  Copyright (c) Microsoft Corporation.  All rights reserved.
 //  Licensed under the MIT License (MIT). See LICENSE in the repo root for license information.
 // ------------------------------------------------------------
@@ -186,23 +186,28 @@ protected static void AppendCustomParameters(OpenApiOperation operation, IList<C
         {
             foreach (var param in customParameters)
             {
-                OpenApiParameter parameter = new OpenApiParameter
+                string documentationUrl = null;
+                if (param.DocumentationURL != null)
+                {
+                    documentationUrl = $" Documentation URL: {param.DocumentationURL}";
+                }
+
+                // DocumentationURL value is to be appended to
+                // the parameter Description property
+                string paramDescription = (param.Description == null) ? documentationUrl?.Remove(0, 1) : param.Description + documentationUrl;
+
+                OpenApiParameter parameter = new()
                 {
                     In = location,
                     Name = param.Name,
-                    Description = param.Description,
+                    Description = paramDescription,
                     Schema = new OpenApiSchema
                     {
                         Type = "string"
                     },
                     Required = param.Required ?? false
                 };
 
-                if (param.DocumentationURL != null)
-                {
-                    parameter.Example = new OpenApiString(param.DocumentationURL ?? "N/A");
-                }
-
                 if (param.ExampleValues != null)
                 {
                     parameter.Examples = new Dictionary<string, OpenApiExample>();

test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EdmFunctionImportOperationHandlerTests.cs

@@ -173,7 +173,31 @@ public void OperationRestrictionsTermWorksToCreateOperationForEdmFunctionImport(
           <PropertyValue Property=""Name"" String=""myhead1"" />
           <PropertyValue Property=""Required"" Bool=""true"" />
         </Record>
-      </Collection>
+        <Record>
+          <PropertyValue Property=""Name"" String=""myhead2"" />
+          <PropertyValue Property = ""Description"" String = ""This is the description for myhead2."" />
+          <PropertyValue Property = ""Required"" Bool = ""false"" />
+        </Record>
+        <Record>
+          <PropertyValue Property=""Name"" String=""myhead3"" />
+          <PropertyValue Property = ""DocumentationURL"" String = ""https://foo.bar.com/myhead3"" />
+          <PropertyValue Property = ""Required"" Bool = ""false"" />
+        </Record>
+        <Record>
+          <PropertyValue Property=""Name"" String=""myhead4"" />
+          <PropertyValue Property = ""Description"" String = ""This is the description for myhead4."" />
+          <PropertyValue Property = ""DocumentationURL"" String = ""https://foo.bar.com/myhead4"" />
+          <PropertyValue Property = ""Required"" Bool = ""false"" />
+          <PropertyValue Property = ""ExampleValues"" >
+            <Collection>
+              <Record>
+                 <PropertyValue Property = ""Value"" String = ""sample"" />
+                 <PropertyValue Property = ""Description"" String = ""The sample description."" />
+                 </Record>
+            </Collection>
+          </PropertyValue>
+        </Record>
+       </Collection>
     </PropertyValue>
     <PropertyValue Property=""Permissions"">
       <Collection>
@@ -262,11 +286,54 @@ public void OperationRestrictionsTermWorksToCreateOperationForEdmFunctionImport(
       }
     }
 ".ChangeLineBreaks(), json);
+
+                // Assert with no DocumentationURL value
+                Assert.Contains(@"
+    {
+      ""name"": ""myhead2"",
+      ""in"": ""header"",
+      ""description"": ""This is the description for myhead2."",
+      ""schema"": {
+        ""type"": ""string""
+      }
+    }
+".ChangeLineBreaks(), json);
+
+                // Assert with no Description value
+                Assert.Contains(@"
+    {
+      ""name"": ""myhead3"",
+      ""in"": ""header"",
+      ""description"": ""Documentation URL: https://foo.bar.com/myhead3"",
+      ""schema"": {
+        ""type"": ""string""
+      }
+    }
+".ChangeLineBreaks(), json);
+
+                // Assert with both DocumentationURL and Description values
+                Assert.Contains(@"
+    {
+      ""name"": ""myhead4"",
+      ""in"": ""header"",
+      ""description"": ""This is the description for myhead4. Documentation URL: https://foo.bar.com/myhead4"",
+      ""schema"": {
+        ""type"": ""string""
+      },
+      ""examples"": {
+        ""example-1"": {
+          ""description"": ""The sample description."",
+          ""value"": ""sample""
+        }
+      }
+    }
+".ChangeLineBreaks(), json);
+
             }
             else
             {
                 Assert.Empty(operation.Security);
             }
         }
     }
-}
+}