Add singular component to openapi when array of singular is openapi response (CarterCommunity#192)

Author: jchannon

samples/CarterSample/Features/CastMembers/CastMemberModule.cs

@@ -3,6 +3,7 @@
     using Carter;
     using Carter.ModelBinding;
     using Carter.Response;
+    using CarterSample.Features.CastMembers.OpenApi;
     using Microsoft.AspNetCore.Http;
     using ValidatorOnlyProject;
 
@@ -21,6 +22,13 @@ public CastMemberModule()
 
                 return res.WriteAsync("OK");
             });
+
+            this.Get<GetCastMembers>("/castmembers", (request, response, routeData) =>
+            {
+                var castMembers = new[] { new CastMember { Name = "Samuel L Jackson" }, new CastMember { Name = "John Travolta" } };
+
+                return response.AsJson(castMembers);
+            });
         }
     }
 }

samples/CarterSample/Features/CastMembers/OpenApi/GetCastMembers.cs

@@ -0,0 +1,25 @@
+namespace CarterSample.Features.CastMembers.OpenApi
+{
+    using System.Collections.Generic;
+    using Carter.OpenApi;
+    using ValidatorOnlyProject;
+
+    public class GetCastMembers : RouteMetaData
+    {
+        public override string Description { get; } = "Returns a list of actors";
+
+        public override RouteMetaDataResponse[] Responses { get; } =
+        {
+            new RouteMetaDataResponse
+            {
+                Code = 200,
+                Description = $"A list of {nameof(CastMember)}s",
+                Response = typeof(IEnumerable<CastMember>)
+            }
+        };
+
+        public override string Tag { get; } = "CastMembers";
+
+        public override string OperationId { get; } = "CastMembers_GetCastMembers";
+    }
+}

src/OpenApi/CarterOpenApi.cs

@@ -218,7 +218,6 @@ private static void CreateOpenApiResponseBody(OpenApiDocument document, KeyValue
                             .Select(x => (Name: x.Name.ToLower(), Type: x.PropertyType.Name.ToLower()))
                             .ToList();
 
-                        var arrbj = new OpenApiArray();
                         var propObj = new OpenApiObject();
 
                         foreach (var propertyInfo in propNames)
@@ -233,16 +232,6 @@ private static void CreateOpenApiResponseBody(OpenApiDocument document, KeyValue
                             Example = propObj
                         };
 
-                        var arrayschema = new OpenApiSchema { Type = "array" };
-
-                        if (arrayType)
-                        {
-                            arrbj.Add(propObj);
-                            arrayschema.Items = schema;
-                        }
-
-                        var respObj = arrayType ? new OpenApiObject { { responseType.Name.ToLower(), arrbj } } : propObj;
-
                         openApiResponse = new OpenApiResponse
                         {
                             Description = valueStatusCode.Description,
@@ -252,9 +241,7 @@ private static void CreateOpenApiResponseBody(OpenApiDocument document, KeyValue
                                     "application/json",
                                     new OpenApiMediaType
                                     {
-                                        //Example = respObj
                                         Schema = new OpenApiSchema { Reference = new OpenApiReference { Id = responseTypeName, Type = ReferenceType.Schema } }
-                                        //Schema = arrayType ? arrayschema : schema
                                     }
                                 }
                             }
@@ -268,9 +255,15 @@ private static void CreateOpenApiResponseBody(OpenApiDocument document, KeyValue
                             }
                             else
                             {
+                                //Add component called "Directors" plural
                                 document.Components.Schemas.Add(responseTypeName,
                                     new OpenApiSchema { Type = "array", Items = new OpenApiSchema { Reference = new OpenApiReference { Id = singularTypeName, Type = ReferenceType.Schema } } });
-                                //TODO Should we check that at the end that any components that are "array" types have a component registered of the  singularTypeName for example you could have IEnumerable<Foo> but Foo is not used in another route so won't be registered in components
+
+                                //If not already added add component called "Director" singular
+                                if (!document.Components.Schemas.ContainsKey(singularTypeName))
+                                {
+                                    document.Components.Schemas.Add(singularTypeName, schema);
+                                }
                             }
                         }
                     }
@@ -449,12 +442,19 @@ private static void CreateOpenApiRequestBody(OpenApiDocument document, KeyValueP
 
                 operation.RequestBody = requestBody;
 
-                //TODO Should we document array request bodies and if so the next line applies:
-                //TODO Should we check that at the end that any components that are "array" types have a component registered of the  singularTypeName for example you could have IEnumerable<Foo> but Foo is not used in another route so won't be registered in components
                 if (!document.Components.Schemas.ContainsKey(requestType.Name))
                 {
                     document.Components.Schemas.Add(requestType.Name, schema);
                 }
+                else
+                {
+                    //TODO
+                    //Currently request schemas contain potentially more information in them via the validation properties.
+                    //If the response openapi processing has added the type as a component already we should override this here as it may contain more info
+                    //One solution to fix this if the response schema needs additional information is to mark each request/response schema accordingly to prevent the race condition of the response
+                    //schema getting listed with its additional data or the request schema getting listed with its validation additional data. Eg "Actors" becomes "Actors_Request" & "Actors_Response"
+                    document.Components.Schemas[requestType.Name] = schema;
+                }
             }
         }
 

test/Carter.Samples.Tests/OpenAPITests.Should_return_Carter_approved_OpenAPI_json.approved.txt

@@ -13,6 +13,27 @@
     }
   ],
   "paths": {
+    "/castmembers": {
+      "get": {
+        "tags": [
+          "CastMembers"
+        ],
+        "description": "Returns a list of actors",
+        "operationId": "CastMembers_GetCastMembers",
+        "responses": {
+          "200": {
+            "description": "A list of CastMembers",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CastMembers"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/actors": {
       "get": {
         "tags": [
@@ -208,6 +229,23 @@
   },
   "components": {
     "schemas": {
+      "CastMembers": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/CastMember"
+        }
+      },
+      "CastMember": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        },
+        "example": {
+          "name": ""
+        }
+      },
       "Actors": {
         "type": "array",
         "items": {