Example value of an empty OpenApiArray disappears after serialization

[CarlosZaldivar2]

The Value property of OpenApiExample is treated as optional and an optional empty IEnumerable is ignored when writing both JSON and YAML. I don't think it's correct, since an empty array or an empty object could be a real example of a response body and we may want to show it to the API's user.

Minimal OpenAPI document with an empty array:

{
    "openapi": "3.0.1",
    "info": {
        "title": "Example API",
        "version": "1.0"
    },
    "paths": {
        "/products": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "examples": {
                                    "Success response - no results": {
                                        "value": []
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

The same document after it has been read and written back by OpenAPI.NET:

{
    "openapi": "3.0.1",
    "info": {
        "title": "Example API",
        "version": "1.0"
    },
    "paths": {
        "/products": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "examples": {
                                    "Success response - no results": {}
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

[MaggieKimani1]

I'm still struggling to see the value of writing out empty collection values as this seems to be by design(subject to change) in the lib.

OpenAPI.NET/src/Microsoft.OpenApi/Writers/OpenApiWriterExtensions.cs

Lines 146 to 149 in b274162

	if (values != null && !values.GetEnumerator().MoveNext())
	{
	return; // Don't render optional empty collections
	}

Required objects are still written out even when empty.

@baywet what do you think?

[CarlosZaldivar2]

@MaggieKimani1 How can I show an empty array as a valid response example, when the library removes the empty array?

[baywet]

@MaggieKimani1 I believe this is pretty much the only valid scenario here.
My worry is that by changing this condition, we'll have side effects in other places where having empty arrays is not desired.
I suggest doing a couple of things here:

• removing the condition, and running unit tests and integration tests for any regression.
• evaluating how much work it'd represent to special case this scenario (through a flag/parameter etc...)