Merge pull request #237 from microsoft/fix/requestBodyAndResponseRepresentationForRefOperations

Fix request body and response representation for ref POST operations

Author: irvinesunday

src/Microsoft.OpenApi.OData.Reader/Common/Constants.cs

@@ -108,11 +108,32 @@ internal static class Constants
         /// <summary>
         /// Name used for reference update.
         /// </summary>
-        public static string ReferenceUpdateSchemaName = "ReferenceUpdateSchema";
+        public static string ReferenceUpdateSchemaName = "ReferenceUpdate";
+
 
+        /// <summary>
+        /// Name used for reference update.
+        /// </summary>
+        public static string ReferenceCreateSchemaName = "ReferenceCreate";
+
+        /// <summary>
+        /// Name used for reference request POST body.
+        /// </summary>
+        public static string ReferencePostRequestBodyName = "refPostBody";
+
+        /// <summary>
+        /// Name used for reference request PUT body.
+        /// </summary>
+        public static string ReferencePutRequestBodyName = "refPutBody";
+        
         /// <summary>
         /// The odata type name.
         /// </summary>
         public static string OdataType = "@odata.type";
+
+        /// <summary>
+        /// The odata id.
+        /// </summary>
+        public static string OdataId = "@odata.id";
     }
 }

src/Microsoft.OpenApi.OData.Reader/Generator/OpenApiComponentsGenerator.cs

@@ -28,7 +28,8 @@ public static OpenApiComponents CreateComponents(this ODataContext context)
             // "components": {
             //   "schemas": …,
             //   "parameters": …,
-            //   "responses": …
+            //   "responses": …,
+            //   "requestBodies": … 
             //  }
             return new OpenApiComponents
             {
@@ -45,13 +46,15 @@ public static OpenApiComponents CreateComponents(this ODataContext context)
                 // It allows defining responses that can be reused across operations of the service.
                 Responses = context.CreateResponses(),
 
-                // Make others as null.
-                RequestBodies = null,
+                // The value of requestBodies is a map of RequestBody Objects.
+                // It allows refining request bodies that can be reused across operations of the service.
+                RequestBodies = context.CreateRequestBodies(),
 
                 Examples = context.CreateExamples(),
 
                 SecuritySchemes = context.CreateSecuritySchemes(),
 
+                // Make others as null.
                 Links = null,
 
                 Callbacks = null,

src/Microsoft.OpenApi.OData.Reader/Generator/OpenApiRequestBodyGenerator.cs

@@ -85,5 +85,90 @@ public static OpenApiRequestBody CreateRequestBody(this ODataContext context, IE
 
             return requestBody;
         }
+
+        /// <summary>
+        /// Create a dictionary of <see cref="OpenApiRequestBody"/> indexed by ref name.
+        /// </summary>
+        /// <param name="context">The OData context.</param>
+        /// <returns>The created dictionary of <see cref="OpenApiRequestBody"/> indexed by ref name</returns>
+        public static IDictionary<string, OpenApiRequestBody> CreateRequestBodies(this ODataContext context)
+        {
+            Utils.CheckArgumentNull(context, nameof(context));
+
+            return new Dictionary<string, OpenApiRequestBody>
+            {
+                {
+                    Constants.ReferencePostRequestBodyName,
+                    CreateRefPostRequestBody() 
+                },
+                {
+                    Constants.ReferencePutRequestBodyName,
+                    CreateRefPutRequestBody()
+                }
+            };
+        }
+
+        /// <summary>
+        /// Create a <see cref="OpenApiRequestBody"/> to be reused across ref POST operations
+        /// </summary>
+        /// <returns>The created <see cref="OpenApiRequestBody"/></returns>
+        private static OpenApiRequestBody CreateRefPostRequestBody()
+        {
+            OpenApiSchema schema = new()
+            {
+                UnresolvedReference = true,
+                Reference = new OpenApiReference
+                {
+                    Type = ReferenceType.Schema,
+                    Id = Constants.ReferenceCreateSchemaName
+                }
+            };
+            return new OpenApiRequestBody
+            {
+                Required = true,
+                Description = "New navigation property ref value",
+                Content = new Dictionary<string, OpenApiMediaType>
+                {
+                    {
+                        Constants.ApplicationJsonMediaType, new OpenApiMediaType
+                        {
+                            Schema = schema
+                        }
+                    }
+                }
+            };
+        }
+
+        /// <summary>
+        /// Create a <see cref="OpenApiRequestBody"/> to be reused across ref PUT operations
+        /// </summary>
+        /// <returns>The created <see cref="OpenApiRequestBody"/></returns>
+        private static OpenApiRequestBody CreateRefPutRequestBody()
+        {
+            OpenApiSchema schema = new()
+            {
+                UnresolvedReference = true,
+                Reference = new OpenApiReference
+                {
+                    Type = ReferenceType.Schema,
+                    Id = Constants.ReferenceUpdateSchemaName
+                }
+            };
+
+            return new OpenApiRequestBody
+            {
+                Required = true,
+                Description = "New navigation property ref values",
+                Content = new Dictionary<string, OpenApiMediaType>
+                {
+                    {
+                        Constants.ApplicationJsonMediaType, new OpenApiMediaType
+                        {
+                            Schema = schema
+                        }
+                    }
+                }
+            };
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/Generator/OpenApiSchemaGenerator.cs

@@ -96,16 +96,27 @@ public static IDictionary<string, OpenApiSchema> CreateSchemas(this ODataContext
             if(context.HasAnyNonContainedCollections())                                        
             {
                 schemas[$"String{Constants.CollectionSchemaSuffix}"] = CreateCollectionSchema(context, new OpenApiSchema { Type = "string" }, "string");
-                schemas[Constants.ReferenceUpdateSchemaName] = new()
-                {
-                    Type = "object",
-                    Properties = new Dictionary<string, OpenApiSchema>
+            }
+
+            schemas[Constants.ReferenceUpdateSchemaName] = new()
+            {
+                Type = "object",
+                Properties = new Dictionary<string, OpenApiSchema>
                     {
-                        {"@odata.id", new OpenApiSchema { Type = "string", Nullable = false }},
+                        {Constants.OdataId, new OpenApiSchema { Type = "string", Nullable = false }},
                         {Constants.OdataType, new OpenApiSchema { Type = "string", Nullable = true }},
                     }
-                };
-            }
+            };
+
+            schemas[Constants.ReferenceCreateSchemaName] = new()
+            {
+                Type = "object",
+                Properties = new Dictionary<string, OpenApiSchema>
+                {
+                    {Constants.OdataId, new OpenApiSchema { Type = "string", Nullable = false }}
+                },
+                AdditionalProperties = new OpenApiSchema { Type = "object" }
+            };
 
             return schemas;
         }

src/Microsoft.OpenApi.OData.Reader/Microsoft.OpenAPI.OData.Reader.csproj

@@ -15,7 +15,7 @@
     <TargetFrameworks>netstandard2.0</TargetFrameworks>
     <PackageId>Microsoft.OpenApi.OData</PackageId>
     <SignAssembly>true</SignAssembly>
-    <Version>1.0.11-preview4</Version>
+    <Version>1.0.11-preview5</Version>
     <Description>This package contains the codes you need to convert OData CSDL to Open API Document of Model.</Description>
     <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
     <PackageTags>Microsoft OpenApi OData EDM</PackageTags>
@@ -26,6 +26,7 @@
 - Add error ranges for OData actions when ErrorResponsesAsDefault is set to false #218
 - Fixes missing bound operations on some navigation property paths #201
 - Provides support for using success status code range 2XX #153
+- Fixes request body and response representation for ref POST and PUT operations #228
 - Adds discriminator object to complex types which have derived types #233
 - Adds @odata.type property and makes this a required property in schemas that have discriminator objects #243
     </PackageReleaseNotes>

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

@@ -5,6 +5,7 @@
 
 using System.Collections.Generic;
 using System.Linq;
+using Microsoft.OData.Edm;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.OData.Common;
 using Microsoft.OpenApi.OData.Generator;
@@ -38,24 +39,13 @@ protected override void SetBasicInfo(OpenApiOperation operation)
         /// <inheritdoc/>
         protected override void SetRequestBody(OpenApiOperation operation)
         {
-            OpenApiSchema schema = new OpenApiSchema
-            {
-                Type = "object",
-                AdditionalProperties = new OpenApiSchema { Type = "object" }
-            };
-
             operation.RequestBody = new OpenApiRequestBody
             {
-                Required = true,
-                Description = "New navigation property ref value",
-                Content = new Dictionary<string, OpenApiMediaType>
+                UnresolvedReference = true,
+                Reference = new OpenApiReference
                 {
-                    {
-                        Constants.ApplicationJsonMediaType, new OpenApiMediaType
-                        {
-                            Schema = schema
-                        }
-                    }
+                    Type = ReferenceType.RequestBody,
+                    Id = Constants.ReferencePostRequestBodyName
                 }
             };
 
@@ -65,29 +55,11 @@ protected override void SetRequestBody(OpenApiOperation operation)
         /// <inheritdoc/>
         protected override void SetResponses(OpenApiOperation operation)
         {
-            OpenApiSchema schema = new OpenApiSchema
-            {
-                Type = "object"
-            };
-
             operation.Responses = new OpenApiResponses
             {
                 {
-                    Context.Settings.UseSuccessStatusCodeRange ? Constants.StatusCodeClass2XX : Constants.StatusCode201,
-                    new OpenApiResponse
-                    {
-                        Description = "Created navigation property link.",
-                        Content = new Dictionary<string, OpenApiMediaType>
-                        {
-                            {
-                                Constants.ApplicationJsonMediaType,
-                                new OpenApiMediaType
-                                {
-                                    Schema = schema
-                                }
-                            }
-                        }
-                    }
+                    Constants.StatusCode204,
+                    new OpenApiResponse { Description = "Success" } 
                 }
             };
 

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

@@ -40,16 +40,11 @@ protected override void SetRequestBody(OpenApiOperation operation)
         {
             operation.RequestBody = new OpenApiRequestBody
             {
-                Required = true,
-                Description = "New navigation property ref values",
-                Content = new Dictionary<string, OpenApiMediaType>
-                {
-                    {
-                        Constants.ApplicationJsonMediaType, new OpenApiMediaType
-                        {
-                            Schema = GetOpenApiSchema()
-                        }
-                    }
+                UnresolvedReference = true,
+                Reference = new OpenApiReference
+                {              
+                    Type = ReferenceType.RequestBody,
+                    Id = Constants.ReferencePutRequestBodyName
                 }
             };
 
@@ -59,7 +54,15 @@ protected override void SetRequestBody(OpenApiOperation operation)
         /// <inheritdoc/>
         protected override void SetResponses(OpenApiOperation operation)
         {
-    		operation.AddErrorResponses(Context.Settings, true, GetOpenApiSchema());
+            operation.Responses = new OpenApiResponses
+            {
+                {
+                    Constants.StatusCode204,
+                    new OpenApiResponse { Description = "Success" }
+                }
+            };
+
+            operation.AddErrorResponses(Context.Settings, false);
             base.SetResponses(operation);
         }
 
@@ -90,18 +93,5 @@ protected override void AppendCustomParameters(OpenApiOperation operation)
                 AppendCustomParameters(operation, Restriction.UpdateRestrictions.CustomQueryOptions, ParameterLocation.Query);
             }
         }
-
-        private OpenApiSchema GetOpenApiSchema()
-        {
-            return new()
-            {
-                UnresolvedReference = true,
-                Reference = new OpenApiReference
-                {
-                    Id = Constants.ReferenceUpdateSchemaName,
-                    Type = ReferenceType.Schema
-                },
-            };
-        }
     }
 }

test/Microsoft.OpenAPI.OData.Reader.Tests/Generator/OpenApiComponentsGeneratorTests.cs

@@ -38,7 +38,7 @@ public void CreateComponentsReturnsForEmptyModel()
             Assert.NotNull(components.Schemas);
             Assert.NotNull(components.Parameters);
             Assert.NotNull(components.Responses);
-            Assert.Null(components.RequestBodies);
+            Assert.NotNull(components.RequestBodies);
         }
     }
 }

test/Microsoft.OpenAPI.OData.Reader.Tests/Generator/OpenApiRequestBodyGeneratorTests.cs

@@ -150,5 +150,21 @@ public void CreateRequestBodyForActionReturnCorrectRequestBody()
             Assert.Equal("param", parameter.Key);
             Assert.Equal("string", parameter.Value.Type);
         }
+
+        [Fact]
+        public void CreateRefRequestBodies()
+        {
+            // Arrange
+            ODataContext context = new ODataContext(_model);
+
+            // Act
+            var requestBodies = context.CreateRequestBodies();
+            requestBodies.TryGetValue(Common.Constants.ReferencePostRequestBodyName, out Models.OpenApiRequestBody refPostBody);
+
+            // Assert
+            Assert.NotNull(refPostBody);
+            Assert.Equal("New navigation property ref value", refPostBody.Description);
+            Assert.Equal(Common.Constants.ReferenceCreateSchemaName, refPostBody.Content.First().Value.Schema.Reference.Id);
+        }
     }
 }

test/Microsoft.OpenAPI.OData.Reader.Tests/Generator/OpenApiSchemaGeneratorTests.cs

@@ -59,6 +59,30 @@ public void CreatesCollectionResponseSchema()
             Assert.Equal("string", stringCollectionResponse.Properties["value"].Items.Type);
         }
 
+        [Fact]
+        public void CreatesRefRequestBodySchema()
+        {
+            // Arrange
+            IEdmModel model = EdmModelHelper.TripServiceModel;
+            OpenApiConvertSettings settings = new()
+            {
+                EnableOperationId = true,
+                EnablePagination = true,
+            };
+            ODataContext context = new(model, settings);
+
+            // Act & Assert
+            var schemas = context.CreateSchemas();
+
+            schemas.TryGetValue(Constants.ReferenceCreateSchemaName, out OpenApiSchema refRequestBody);
+
+            Assert.NotNull(refRequestBody);
+            Assert.Equal("object", refRequestBody.Type);
+            Assert.Equal(Constants.OdataId, refRequestBody.Properties.First().Key);
+            Assert.Equal("string", refRequestBody.Properties.First().Value.Type);
+            Assert.Equal("object", refRequestBody.AdditionalProperties.Type);
+        }
+
         #region StructuredTypeSchema
         [Fact]
         public void CreateStructuredTypeSchemaThrowArgumentNullContext()