Skip to content

Example value of an empty OpenApiArray disappears after serialization #1643

Description

@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": {}
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Activity

  1. MaggieKimani1 commented on Aug 1, 2024

    @MaggieKimani1
    Contributor

    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.

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

    Required objects are still written out even when empty.

    Vincent Biret (@baywet) what do you think?

  2. CarlosZaldivar2 commented on Aug 1, 2024

    @CarlosZaldivar2
    Author

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

  3. baywet commented on Aug 1, 2024

    @baywet
    Member

    Maggie Kimani (@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...)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions